@untemps/react-vocal 2.0.0-beta.2 → 2.0.0-beta.4

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@untemps/react-vocal",
-	"version": "2.0.0-beta.2",
+	"version": "2.0.0-beta.4",
 	"author": "Vincent Le Badezet <v.lebadezet@untemps.net>",
 	"repository": "git@github.com:untemps/react-vocal.git",
 	"license": "MIT",

package/src/components/Vocal.jsx

@@ -8,12 +8,22 @@ import useCommands from '../hooks/useCommands'
 
 import Icon from './Icon'
 
+const tryMatchCommand = (segmentData, trigger) => {
+	for (const { alternatives } of segmentData) {
+		for (const a of alternatives) {
+			if (trigger(a) !== null) return
+		}
+	}
+}
+
 const Vocal = ({
 	children,
 	commands = null,
 	lang = 'en-US',
 	grammars = null,
 	timeout = 3000,
+	precision = 0.4, // Fuse.js score threshold for phrase commands only; single-word commands always use exact lookup
+	maxAlternatives = 1,
 	ariaLabel = 'start recognition',
 	style = null,
 	className = null,
@@ -30,8 +40,8 @@ const Vocal = ({
 	const buttonRef = useRef(null)
 	const [isListening, setIsListening] = useState(false)
 
-	const [, { start, stop, subscribe, unsubscribe }] = useVocal(lang, grammars, __rsInstance)
-	const triggerCommand = useCommands(commands)
+	const [, { start, stop, subscribe, unsubscribe }] = useVocal(lang, grammars, maxAlternatives, __rsInstance)
+	const triggerCommand = useCommands(commands, precision)
 
 	const propsRef = useRef({})
 	propsRef.current = { onStart, onEnd, onSpeechStart, onSpeechEnd, onResult, onError, onNoMatch }
@@ -52,7 +62,6 @@ const Vocal = ({
 			stop()
 		} catch (error) {
 			propsRef.current.onError?.(error)
-		} finally {
 			unsubscribeAllRef.current?.()
 		}
 	}, [stop])
@@ -82,11 +91,25 @@ const Vocal = ({
 	)
 
 	const _onResult = useCallback(
-		(event, result) => {
+		(event) => {
+			const segmentData = Array.from(event?.results ?? [], (segment) => {
+				let best = { confidence: -Infinity, transcript: '' }
+				const alternatives = []
+				for (let j = 0; j < segment.length; j++) {
+					const alt = segment[j]
+					alternatives.push(alt.transcript ?? '')
+					if (alt.confidence === undefined || alt.confidence > best.confidence) {
+						best = alt
+					}
+				}
+				return { best: best.transcript ?? '', alternatives }
+			})
+			const transcript = segmentData.map((s) => s.best).join('')
+
 			stopTimer()
 			stopRecognition()
-			triggerCommandRef.current(result)
-			propsRef.current.onResult?.(result, event)
+			tryMatchCommand(segmentData, triggerCommandRef.current)
+			propsRef.current.onResult?.(transcript, event)
 		},
 		[stopTimer, stopRecognition]
 	)
@@ -111,8 +134,12 @@ const Vocal = ({
 	const _onEnd = useCallback(
 		(e) => {
 			stopTimer()
-			stopRecognition()
-			propsRef.current.onEnd?.(e)
+			try {
+				stopRecognition()
+				unsubscribeAllRef.current?.()
+			} finally {
+				propsRef.current.onEnd?.(e)
+			}
 		},
 		[stopTimer, stopRecognition]
 	)

package/src/components/__tests__/Vocal.test.jsx

@@ -427,4 +427,185 @@ describe('Vocal', () => {
 
 		expect(onErrorV1).not.toHaveBeenCalled()
 	})
+
+	it('triggers command matched on first segment in multi-segment result', async () => {
+		const callback = vi.fn()
+		const recognition = new SpeechRecognitionWrapper()
+		const commands = { hello: callback }
+		const { getByTestId } = render(getInstance({ __rsInstance: recognition, commands }))
+
+		await act(async () => {
+			fireEvent.click(getByTestId('__vocal-root__'))
+			recognition.instance.say([
+				[{ transcript: 'hello', confidence: 0.9 }],
+				[{ transcript: 'world', confidence: 0.8 }],
+			])
+			await waitFor(() => expect(callback).toHaveBeenCalledWith('hello'))
+		})
+	})
+
+	it('triggers command matched on second segment in multi-segment result', async () => {
+		const callback = vi.fn()
+		const recognition = new SpeechRecognitionWrapper()
+		const commands = { world: callback }
+		const { getByTestId } = render(getInstance({ __rsInstance: recognition, commands }))
+
+		await act(async () => {
+			fireEvent.click(getByTestId('__vocal-root__'))
+			recognition.instance.say([
+				[{ transcript: 'hello', confidence: 0.9 }],
+				[{ transcript: 'world', confidence: 0.8 }],
+			])
+			await waitFor(() => expect(callback).toHaveBeenCalledWith('world'))
+		})
+	})
+
+	it('does not trigger command when no segment matches', async () => {
+		const callback = vi.fn()
+		const recognition = new SpeechRecognitionWrapper()
+		const commands = { foo: callback }
+		const { getByTestId } = render(getInstance({ __rsInstance: recognition, commands }))
+
+		await act(async () => {
+			fireEvent.click(getByTestId('__vocal-root__'))
+			recognition.instance.say([
+				[{ transcript: 'hello', confidence: 0.9 }],
+				[{ transcript: 'world', confidence: 0.8 }],
+			])
+			await new Promise((r) => setTimeout(r, 100))
+		})
+
+		expect(callback).not.toHaveBeenCalled()
+	})
+
+	it('fires only the first matching command when multiple segments each match a different command', async () => {
+		const callbackHello = vi.fn()
+		const callbackWorld = vi.fn()
+		const recognition = new SpeechRecognitionWrapper()
+		const commands = { hello: callbackHello, world: callbackWorld }
+		const { getByTestId } = render(getInstance({ __rsInstance: recognition, commands }))
+
+		await act(async () => {
+			fireEvent.click(getByTestId('__vocal-root__'))
+			recognition.instance.say([
+				[{ transcript: 'hello', confidence: 0.9 }],
+				[{ transcript: 'world', confidence: 0.8 }],
+			])
+			await waitFor(() => expect(callbackHello).toHaveBeenCalledWith('hello'))
+		})
+
+		expect(callbackWorld).not.toHaveBeenCalled()
+	})
+
+	it('passes full joined transcript to onResult regardless of command segment matching', async () => {
+		const onResult = vi.fn()
+		const recognition = new SpeechRecognitionWrapper()
+		const commands = { hello: vi.fn() }
+		const { getByTestId } = render(getInstance({ __rsInstance: recognition, commands, onResult }))
+
+		await act(async () => {
+			fireEvent.click(getByTestId('__vocal-root__'))
+			recognition.instance.say([
+				[{ transcript: 'hello ', confidence: 0.9 }],
+				[{ transcript: 'world', confidence: 0.8 }],
+			])
+			await waitFor(() => expect(onResult).toHaveBeenCalledWith('hello world', expect.anything()))
+		})
+	})
+
+	it('returns the most confident alternative as the onResult transcript', async () => {
+		const onResult = vi.fn()
+		const recognition = new SpeechRecognitionWrapper()
+		const { getByTestId } = render(getInstance({ __rsInstance: recognition, onResult }))
+
+		await act(async () => {
+			fireEvent.click(getByTestId('__vocal-root__'))
+			recognition.instance.say([[
+				{ transcript: 'bar', confidence: 0.4 },
+				{ transcript: 'foo', confidence: 0.9 },
+				{ transcript: 'baz', confidence: 0.1 },
+			]])
+			await waitFor(() => expect(onResult).toHaveBeenCalledWith('foo', expect.anything()))
+		})
+	})
+
+	it('joins all segments into the onResult transcript', async () => {
+		const onResult = vi.fn()
+		const recognition = new SpeechRecognitionWrapper()
+		const { getByTestId } = render(getInstance({ __rsInstance: recognition, onResult }))
+
+		await act(async () => {
+			fireEvent.click(getByTestId('__vocal-root__'))
+			recognition.instance.say([
+				[{ transcript: 'hello ', confidence: 0.9 }],
+				[{ transcript: 'world', confidence: 0.8 }],
+			])
+			await waitFor(() => expect(onResult).toHaveBeenCalledWith('hello world', expect.anything()))
+		})
+	})
+
+	it('triggers command matched on a word within a multi-word segment', async () => {
+		const callback = vi.fn()
+		const recognition = new SpeechRecognitionWrapper()
+		const commands = { rouge: callback }
+		const { getByTestId } = render(getInstance({ __rsInstance: recognition, commands }))
+
+		await act(async () => {
+			fireEvent.click(getByTestId('__vocal-root__'))
+			recognition.instance.say([[{ transcript: 'je veux du rouge', confidence: 0.9 }]])
+			await waitFor(() => expect(callback).toHaveBeenCalledWith('rouge'))
+		})
+	})
+
+	it('triggers command matched on a secondary alternative (homophone)', async () => {
+		const callback = vi.fn()
+		const recognition = new SpeechRecognitionWrapper()
+		const commands = { vert: callback }
+		const { getByTestId } = render(getInstance({ __rsInstance: recognition, commands, maxAlternatives: 3 }))
+
+		await act(async () => {
+			fireEvent.click(getByTestId('__vocal-root__'))
+			// Primary alternative is the homophone; secondary is the correct word
+			recognition.instance.say([[
+				{ transcript: 'verre', confidence: 0.9 },
+				{ transcript: 'vert', confidence: 0.7 },
+			]])
+			await waitFor(() => expect(callback).toHaveBeenCalledWith('vert'))
+		})
+	})
+
+	it('passes the most confident transcript to onResult even when command matches a secondary alternative', async () => {
+		const onResult = vi.fn()
+		const recognition = new SpeechRecognitionWrapper()
+		const commands = { vert: vi.fn() }
+		const { getByTestId } = render(getInstance({ __rsInstance: recognition, commands, onResult, maxAlternatives: 3 }))
+
+		await act(async () => {
+			fireEvent.click(getByTestId('__vocal-root__'))
+			recognition.instance.say([[
+				{ transcript: 'verre', confidence: 0.9 },
+				{ transcript: 'vert', confidence: 0.7 },
+			]])
+			await waitFor(() => expect(onResult).toHaveBeenCalledWith('verre', expect.anything()))
+		})
+	})
+
+	it('calls onEnd via the end event when stop is asynchronous', async () => {
+		const onEnd = vi.fn()
+		const recognition = new SpeechRecognitionWrapper()
+		const { getByTestId } = render(getInstance({ __rsInstance: recognition, onEnd }))
+
+		// Simulate async stop: override stop() so the end event does not fire immediately
+		recognition.instance.stop = vi.fn()
+
+		await act(async () => {
+			fireEvent.click(getByTestId('__vocal-root__'))
+			recognition.instance.say('Foo')
+			// stopRecognition was called but end has not fired yet — onEnd must not be called
+			expect(onEnd).not.toHaveBeenCalled()
+			// Browser fires end asynchronously after recognition stops
+			recognition.instance.end()
+			await waitFor(() => expect(onEnd).toHaveBeenCalled())
+		})
+	})
 })

package/src/hooks/__tests__/useCommands.test.js

@@ -61,4 +61,29 @@ describe('useCommands', () => {
 		} = renderHook(() => useCommands(commands))
 		expect(triggerCommand('gag')).toBeNull()
 	})
+
+	it('triggers all registered commands when multiple commands are defined', () => {
+		const commands = {
+			rouge: () => 'red',
+			bleu: () => 'blue',
+			jaune: () => 'yellow',
+		}
+		const {
+			result: { current: triggerCommand },
+		} = renderHook(() => useCommands(commands))
+		expect(triggerCommand('rouge')).toBe('red')
+		expect(triggerCommand('bleu')).toBe('blue')
+		expect(triggerCommand('jaune')).toBe('yellow')
+	})
+
+	it('does not match near-homophones with strict precision — rely on maxAlternatives instead', () => {
+		const commands = { vert: () => 'green' }
+		const {
+			result: { current: triggerCommand },
+		} = renderHook(() => useCommands(commands))
+		// 'verre' scores 0.4 against 'vert' — not strictly < STRICT_PRECISION (0.4)
+		expect(triggerCommand('verre')).toBeNull()
+		// The engine surfaces 'vert' as a secondary alternative (score 0) — exact match
+		expect(triggerCommand('vert')).toBe('green')
+	})
 })

package/src/hooks/__tests__/useVocal.test.js

@@ -124,13 +124,18 @@ describe('useVocal', () => {
 			expect(ref.current).toBeDefined()
 		})
 
+		it('passes maxAlternatives to SpeechRecognitionWrapper constructor', () => {
+			renderHook(() => useVocal('en-US', null, 5))
+			expect(SpeechRecognitionWrapper).toHaveBeenCalledWith({ lang: 'en-US', grammars: null, maxAlternatives: 5 })
+		})
+
 		it('uses custom SpeechRecognition instance', () => {
 			const foo = new SpeechRecognitionWrapper()
 			const {
 				result: {
 					current: [ref],
 				},
-			} = renderHook(() => useVocal(null, null, foo))
+			} = renderHook(() => useVocal(null, null, 1, foo))
 			expect(ref.current).toBe(foo)
 		})
 

package/src/hooks/useCommands.js

@@ -1,16 +1,44 @@
+import { useMemo } from 'react'
 import Fuse from 'fuse.js'
 
 const useCommands = (commands, precision = 0.4) => {
-	commands = !!commands
-		? Object.entries(commands)?.reduce((acc, [key, value]) => ({ [key.toLowerCase()]: value }), {})
-		: {}
+	const normalized = useMemo(
+		() =>
+			!!commands
+				? Object.entries(commands).reduce((acc, [key, value]) => ({ ...acc, [key.toLowerCase()]: value }), {})
+				: {},
+		[commands]
+	)
+
+	const keys = useMemo(() => Object.keys(normalized), [normalized])
+
+	// Fuzzy matching is only needed for phrase command keys.
+	// Single-word keys use exact case-insensitive lookup — simpler and no false positives.
+	const hasPhraseKeys = useMemo(() => keys.some((k) => k.includes(' ')), [keys])
+
+	// precision only applies to phrase keys — single-word keys always use exact lookup
+	const fuse = useMemo(
+		() => (hasPhraseKeys ? new Fuse(keys, { includeScore: true, ignoreLocation: true }) : null),
+		[hasPhraseKeys, keys]
+	)
 
 	const triggerCommand = (input) => {
-		const fuse = new Fuse(Object.keys(commands), { includeScore: true, ignoreLocation: true })
+		if (!keys.length) return null
+
+		if (!hasPhraseKeys) {
+			const words = input.trim().split(/\s+/)
+			const targets = words.length > 1 ? words : [input.trim()]
+			for (const w of targets) {
+				const key = w.toLowerCase()
+				if (key in normalized) return normalized[key]?.(w)
+			}
+			return null
+		}
+
 		const result = fuse.search(input).filter((r) => r.score < precision)
-		if (!!result?.length) {
+		if (result?.length) {
 			const key = result[0].item.toLowerCase()
-			return commands[key]?.(input)
+			return normalized[key]?.(input)
 		}
 		return null
 	}

package/src/hooks/useVocal.js

@@ -1,18 +1,18 @@
 import { useCallback, useEffect, useRef } from 'react'
 import { Vocal as SpeechRecognitionWrapper } from '@untemps/vocal'
 
-const useVocal = (lang = 'en-US', grammars = null, __rsInstance = null) => {
+const useVocal = (lang = 'en-US', grammars = null, maxAlternatives = 1, __rsInstance = null) => {
 	const ref = useRef(null)
 
 	useEffect(() => {
 		if (SpeechRecognitionWrapper.isSupported) {
-			ref.current = __rsInstance || new SpeechRecognitionWrapper({ lang, grammars })
+			ref.current = __rsInstance || new SpeechRecognitionWrapper({ lang, grammars, maxAlternatives })
 			return () => {
 				ref.current.abort()
 				ref.current.cleanup()
 			}
 		}
-	}, [lang, grammars, __rsInstance])
+	}, [lang, grammars, maxAlternatives, __rsInstance])
 
 	const start = useCallback(() => {
 		if (ref.current) {

package/vitest.setup.js

@@ -54,19 +54,22 @@ global.SpeechRecognition = vi.fn(function () {
 		abort: vi.fn(function () {
 			handlers.end?.()
 		}),
-		say: vi.fn(function (sentence) {
+		say: vi.fn(function (input) {
 			handlers.speechstart?.()
 
 			const resultEvent = new Event('result')
 			resultEvent.resultIndex = 0
-			resultEvent.results = [[{ transcript: sentence }]]
+			resultEvent.results = Array.isArray(input) ? input : input ? [[{ transcript: input }]] : []
 			handlers.speechend?.()
-			if (sentence) {
+			if (input) {
 				handlers.result?.(resultEvent)
 			} else {
 				handlers.nomatch?.()
 			}
 		}),
+		end: vi.fn(function () {
+			handlers.end?.()
+		}),
 		error: vi.fn(function (err) {
 			handlers.error?.(err)
 		}),