@juspay/svelte-ui-components 2.127.0 → 2.128.0

package/dist/SpeechToText/controller.svelte.d.ts

@@ -0,0 +1,51 @@
+import type { SpeechToTextOptions } from './types';
+/**
+ * Headless speech-to-text over the browser's SpeechRecognition API. Owns the whole
+ * lifecycle a mic button needs — support detection, a one-shot host permission hook,
+ * start-with-retry, interim/final transcript assembly, and a self-hiding error toast —
+ * and exposes it as reactive fields plus callbacks. Rendering stays entirely with the
+ * host; pair it with ChatComposer's voice control (`recording`, `onvoice`).
+ */
+export declare class SpeechToTextController {
+    /** True between the notified start and end of a listening session. */
+    listening: boolean;
+    /** Committed transcript plus the current interim guess; what a composer shows while listening. */
+    interimText: string;
+    errorMessage: string;
+    errorVisible: boolean;
+    supported: boolean;
+    private readonly options;
+    private readonly messages;
+    private readonly errorMessages;
+    private recognition;
+    private instanceGeneration;
+    private transcript;
+    private internalListening;
+    private everInitialized;
+    private errorTimer;
+    private permissionRequested;
+    private permissionGranted;
+    constructor(options?: SpeechToTextOptions);
+    /**
+     * Detects the API and builds a wired recognition instance. Safe to call again
+     * to rebuild after a failure; `start` calls it lazily if the host never did.
+     */
+    initialize(): boolean;
+    start(): void;
+    stop(): void;
+    /**
+     * The mic-button handler: stops when listening, otherwise runs the permission
+     * gate (at most one proactive host request, denial remembered) and starts.
+     */
+    toggle(): Promise<void>;
+    /** Clears the toast timer and tears the recognition instance down. */
+    destroy(): void;
+    private attemptStart;
+    private handleStart;
+    private handleResult;
+    private handleRecognitionError;
+    private handleEnd;
+    private setListening;
+    private showError;
+    private diagnose;
+}

package/dist/SpeechToText/controller.svelte.js

@@ -0,0 +1,314 @@
+const DEFAULT_ERROR_MESSAGES = {
+    'not-allowed': 'Microphone access is blocked. Allow microphone access in your browser settings to use voice input.',
+    'service-not-allowed': 'Microphone access is blocked. Allow microphone access in your browser settings to use voice input.',
+    'no-speech': 'No speech detected. Please speak closer to your microphone and try again.',
+    'audio-capture': 'No microphone found. Please connect a microphone and try again.',
+    network: 'A network error interrupted voice input. Please check your connection and try again.'
+};
+const DEFAULT_MESSAGES = {
+    unsupported: 'Speech recognition not supported in this browser.',
+    initFailed: 'Failed to initialize speech recognition service.',
+    startFailed: 'Recognition service could not be initialized for starting.',
+    startRetryFailedPrefix: 'Failed to start speech recognition even after retry: ',
+    fallback: 'Could not start voice input. Please try again.',
+    permissionDenied: 'Microphone permission denied.',
+    permissionPreviouslyDenied: 'Microphone permission was previously denied.',
+    permissionRequestFailed: 'Failed to request microphone permission.'
+};
+const DEFAULT_ERROR_TIMEOUT_MS = 4000;
+function defaultRecognitionConstructor() {
+    if (typeof window === 'undefined') {
+        return null;
+    }
+    const speechWindow = window;
+    return speechWindow.SpeechRecognition ?? speechWindow.webkitSpeechRecognition ?? null;
+}
+function errorName(raw) {
+    return raw instanceof Error ? raw.name : 'UnknownError';
+}
+function errorDetail(raw) {
+    return raw instanceof Error ? raw.message : String(raw);
+}
+function permissionRejectionDetail(raw) {
+    if (typeof raw === 'object' &&
+        raw !== null &&
+        'error' in raw &&
+        typeof raw.error === 'string' &&
+        raw.error.length > 0) {
+        return raw.error;
+    }
+    if (raw instanceof Error && raw.message.length > 0) {
+        return raw.message;
+    }
+    return null;
+}
+/**
+ * Headless speech-to-text over the browser's SpeechRecognition API. Owns the whole
+ * lifecycle a mic button needs — support detection, a one-shot host permission hook,
+ * start-with-retry, interim/final transcript assembly, and a self-hiding error toast —
+ * and exposes it as reactive fields plus callbacks. Rendering stays entirely with the
+ * host; pair it with ChatComposer's voice control (`recording`, `onvoice`).
+ */
+export class SpeechToTextController {
+    /** True between the notified start and end of a listening session. */
+    listening = $state(false);
+    /** Committed transcript plus the current interim guess; what a composer shows while listening. */
+    interimText = $state('');
+    errorMessage = $state('');
+    errorVisible = $state(false);
+    supported = $state(false);
+    options;
+    messages;
+    errorMessages;
+    recognition = null;
+    // Bumped per initialize(); handlers captured by a discarded instance compare
+    // against it so a late onend/onerror from the old engine cannot end the new
+    // session (start() rebuilds the instance on its retry path).
+    instanceGeneration = 0;
+    transcript = '';
+    internalListening = false;
+    everInitialized = false;
+    errorTimer = null;
+    permissionRequested = false;
+    permissionGranted = null;
+    constructor(options = {}) {
+        this.options = options;
+        this.messages = { ...DEFAULT_MESSAGES, ...options.messages };
+        this.errorMessages = { ...DEFAULT_ERROR_MESSAGES, ...options.errorMessages };
+    }
+    /**
+     * Detects the API and builds a wired recognition instance. Safe to call again
+     * to rebuild after a failure; `start` calls it lazily if the host never did.
+     */
+    initialize() {
+        this.everInitialized = true;
+        const getConstructor = this.options.getRecognitionConstructor ?? defaultRecognitionConstructor;
+        const RecognitionApi = getConstructor();
+        this.supported = RecognitionApi !== null;
+        if (RecognitionApi === null) {
+            this.recognition = null;
+            return false;
+        }
+        try {
+            const instance = new RecognitionApi();
+            this.instanceGeneration += 1;
+            const generation = this.instanceGeneration;
+            const isCurrent = () => generation === this.instanceGeneration;
+            instance.continuous = this.options.continuous ?? false;
+            instance.interimResults = this.options.interimResults ?? true;
+            instance.lang = this.options.lang ?? 'en-US';
+            instance.onstart = () => {
+                if (isCurrent()) {
+                    this.handleStart();
+                }
+            };
+            instance.onresult = (event) => {
+                if (isCurrent()) {
+                    this.handleResult(event);
+                }
+            };
+            instance.onerror = (event) => {
+                if (isCurrent()) {
+                    this.handleRecognitionError(event);
+                }
+            };
+            instance.onend = () => {
+                if (isCurrent()) {
+                    this.handleEnd();
+                }
+            };
+            this.recognition = instance;
+            return true;
+        }
+        catch (error) {
+            this.supported = false;
+            this.recognition = null;
+            this.diagnose('initializeFailed', { error: errorDetail(error) });
+            this.showError(this.messages.initFailed);
+            return false;
+        }
+    }
+    start() {
+        if (!this.everInitialized) {
+            this.initialize();
+        }
+        if (!this.supported) {
+            this.showError(this.messages.unsupported);
+            return;
+        }
+        if (this.recognition === null && !this.initialize()) {
+            return;
+        }
+        this.attemptStart(false);
+    }
+    stop() {
+        if (this.internalListening) {
+            this.internalListening = false;
+            this.setListening(false);
+        }
+        if (this.recognition !== null) {
+            this.recognition.stop();
+        }
+    }
+    /**
+     * The mic-button handler: stops when listening, otherwise runs the permission
+     * gate (at most one proactive host request, denial remembered) and starts.
+     */
+    async toggle() {
+        if (this.internalListening) {
+            this.stop();
+            return;
+        }
+        const requestPermission = this.options.requestPermission ?? null;
+        if (requestPermission === null) {
+            this.start();
+            return;
+        }
+        if (this.permissionRequested) {
+            if (this.permissionGranted === false) {
+                this.showError(this.messages.permissionPreviouslyDenied);
+            }
+            else {
+                this.start();
+            }
+            return;
+        }
+        const pending = requestPermission();
+        if (pending === null) {
+            this.start();
+            return;
+        }
+        this.permissionRequested = true;
+        try {
+            const result = await pending;
+            this.permissionGranted = result.granted;
+            if (result.granted) {
+                this.start();
+            }
+            else {
+                const denialMessage = typeof result.error === 'string' && result.error.length > 0
+                    ? result.error
+                    : this.messages.permissionDenied;
+                this.showError(denialMessage);
+            }
+        }
+        catch (error) {
+            this.permissionGranted = false;
+            this.showError(permissionRejectionDetail(error) ?? this.messages.permissionRequestFailed);
+        }
+    }
+    /** Clears the toast timer and tears the recognition instance down. */
+    destroy() {
+        if (this.errorTimer !== null) {
+            clearTimeout(this.errorTimer);
+            this.errorTimer = null;
+        }
+        if (this.recognition !== null) {
+            try {
+                this.recognition.abort();
+            }
+            catch (abortError) {
+                this.diagnose('recognitionAbortErrorOnDestroy', { error: errorDetail(abortError) });
+            }
+            this.recognition = null;
+        }
+        this.internalListening = false;
+        // abort() is not guaranteed to fire onend, so clear the public state too —
+        // a consumer's recording indicator must not survive teardown.
+        if (this.listening) {
+            this.setListening(false);
+        }
+    }
+    attemptStart(isRetry) {
+        if (this.recognition === null) {
+            this.showError(this.messages.startFailed);
+            this.internalListening = false;
+            this.setListening(false);
+            return;
+        }
+        try {
+            this.internalListening = true;
+            this.errorMessage = '';
+            this.errorVisible = false;
+            this.recognition.start();
+        }
+        catch (error) {
+            if (!isRetry) {
+                try {
+                    this.recognition.abort();
+                }
+                catch (abortError) {
+                    this.diagnose('recognitionAbortErrorOnRetry', {
+                        error: errorDetail(abortError),
+                        rawError: String(abortError)
+                    });
+                }
+                if (this.initialize()) {
+                    this.attemptStart(true);
+                }
+                else {
+                    this.internalListening = false;
+                    this.setListening(false);
+                }
+            }
+            else {
+                this.showError(`${this.messages.startRetryFailedPrefix}${errorName(error)} - ${errorDetail(error)}`);
+                this.internalListening = false;
+                this.setListening(false);
+            }
+        }
+    }
+    handleStart() {
+        this.transcript = this.options.seedTranscript ? this.options.seedTranscript() : '';
+        this.interimText = this.transcript;
+        this.internalListening = true;
+        this.setListening(true);
+    }
+    handleResult(event) {
+        let finalTranscript = '';
+        let currentInterimTranscript = '';
+        for (let index = event.resultIndex; index < event.results.length; index += 1) {
+            const result = event.results[index];
+            if (result.isFinal) {
+                finalTranscript += result[0].transcript;
+            }
+            else {
+                currentInterimTranscript += result[0].transcript;
+            }
+        }
+        this.interimText =
+            this.transcript + (currentInterimTranscript ? ' ' + currentInterimTranscript : '');
+        if (finalTranscript) {
+            this.transcript = this.transcript ? `${this.transcript.trimEnd()} ` : '';
+            this.transcript += finalTranscript;
+            this.options.onTranscript?.(this.transcript);
+        }
+    }
+    handleRecognitionError(event) {
+        this.internalListening = false;
+        this.setListening(false);
+        this.showError(this.errorMessages[event.error] ?? this.messages.fallback, event.error);
+    }
+    handleEnd() {
+        this.internalListening = false;
+        this.setListening(false);
+    }
+    setListening(listening) {
+        this.listening = listening;
+        this.options.onListeningChange?.(listening);
+    }
+    showError(message, code = null) {
+        this.errorMessage = message;
+        this.errorVisible = true;
+        if (this.errorTimer !== null) {
+            clearTimeout(this.errorTimer);
+        }
+        this.errorTimer = setTimeout(() => {
+            this.errorVisible = false;
+        }, this.options.errorTimeoutMs ?? DEFAULT_ERROR_TIMEOUT_MS);
+        this.options.onError?.(message, code);
+    }
+    diagnose(event, detail) {
+        this.options.onDiagnostic?.(event, detail);
+    }
+}

package/dist/SpeechToText/types.d.ts

@@ -0,0 +1,75 @@
+export type SpeechRecognitionAlternative = {
+    transcript: string;
+};
+export type SpeechRecognitionResultItem = {
+    0: SpeechRecognitionAlternative;
+    isFinal: boolean;
+};
+export type SpeechRecognitionResultEvent = {
+    resultIndex: number;
+    results: SpeechRecognitionResultItem[];
+};
+export type SpeechRecognitionErrorEvent = {
+    error: string;
+};
+/**
+ * The browser's non-standard SpeechRecognition surface, reduced to the members the
+ * controller drives. lib.dom does not declare the API, so the shape lives here and
+ * a fake implementing it can be injected for tests and demos.
+ */
+export type SpeechRecognitionLike = {
+    continuous: boolean;
+    interimResults: boolean;
+    lang: string;
+    start: () => void;
+    stop: () => void;
+    abort: () => void;
+    onstart: () => void;
+    onresult: (event: SpeechRecognitionResultEvent) => void;
+    onerror: (event: SpeechRecognitionErrorEvent) => void;
+    onend: () => void;
+};
+export type SpeechRecognitionConstructor = new () => SpeechRecognitionLike;
+export type SpeechPermissionResult = {
+    granted: boolean;
+    error?: string;
+};
+/** User-facing copy the controller emits outside the per-error-code map. */
+export type SpeechToTextMessages = {
+    unsupported: string;
+    initFailed: string;
+    startFailed: string;
+    startRetryFailedPrefix: string;
+    fallback: string;
+    permissionDenied: string;
+    permissionPreviouslyDenied: string;
+    permissionRequestFailed: string;
+};
+export type SpeechToTextOptions = {
+    lang?: string;
+    continuous?: boolean;
+    interimResults?: boolean;
+    /** How long an error toast stays visible. */
+    errorTimeoutMs?: number;
+    /** Per-recognition-error-code messages, merged over the built-in map. */
+    errorMessages?: Record<string, string>;
+    /** Copy overrides, merged over the built-in defaults. */
+    messages?: Partial<SpeechToTextMessages>;
+    /** Resolves the recognition constructor; defaults to the browser's. Injectable for tests. */
+    getRecognitionConstructor?: () => SpeechRecognitionConstructor | null;
+    /**
+     * Host permission hook (e.g. a native shell's microphone bridge). Called on a start
+     * attempt; return null to mean "no bridge here", which falls through to the standard
+     * browser flow without consuming the single proactive request. A resolved denial is
+     * remembered and short-circuits later attempts.
+     */
+    requestPermission?: () => Promise<SpeechPermissionResult> | null;
+    /** Text the transcript starts from when listening begins (e.g. the composer's current value). */
+    seedTranscript?: () => string;
+    /** Fires with the accumulated transcript each time a final result lands. */
+    onTranscript?: (transcript: string) => void;
+    onListeningChange?: (listening: boolean) => void;
+    onError?: (message: string, code: string | null) => void;
+    /** Non-fatal internals worth logging; hosts wire this to their telemetry. */
+    onDiagnostic?: (event: string, detail: Record<string, string | number | boolean | null>) => void;
+};

package/dist/SpeechToText/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -93,6 +93,7 @@ export { pauseAllConfirmationTimers } from './HITL/timers';
 export { default as Resizable } from './Resizable/Resizable.svelte';
 export { ChatController } from './Chat/controller.svelte';
 export { partyOf } from './Chat/roles';
+export { SpeechToTextController } from './SpeechToText/controller.svelte';
 export type * from './Button/properties';
 export type * from './Modal/properties';
 export type * from './Input/properties';
@@ -172,6 +173,7 @@ export type * from './FileDropzoneTrigger/properties';
 export type * from './_chart/highlight';
 export type * from './Chat/properties';
 export type * from './Chat/types';
+export type * from './SpeechToText/types';
 export type * from './ChatHeader/properties';
 export type * from './ChatMessage/properties';
 export type * from './ChatMessageList/properties';

package/dist/index.js

@@ -93,5 +93,6 @@ export { pauseAllConfirmationTimers } from './HITL/timers';
 export { default as Resizable } from './Resizable/Resizable.svelte';
 export { ChatController } from './Chat/controller.svelte';
 export { partyOf } from './Chat/roles';
+export { SpeechToTextController } from './SpeechToText/controller.svelte';
 export { validateInput } from './utils';
 export { formatNumberIndian } from './_chart/format';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/svelte-ui-components",
-  "version": "2.127.0",
+  "version": "2.128.0",
   "description": "A themeable Svelte 5 UI component library with CSS custom property driven styling",
   "keywords": [
     "svelte",