@untemps/react-vocal 2.0.0-beta.3 → 2.0.0-beta.5

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@untemps/react-vocal",
-	"version": "2.0.0-beta.3",
+	"version": "2.0.0-beta.5",
 	"author": "Vincent Le Badezet <v.lebadezet@untemps.net>",
 	"repository": "git@github.com:untemps/react-vocal.git",
 	"license": "MIT",
@@ -27,6 +27,7 @@
 	},
 	"devDependencies": {
 		"@commitlint/cli": "^20.5.3",
+		"fuse.js": "^7.3.0",
 		"@commitlint/config-conventional": "^20.5.3",
 		"@semantic-release/changelog": "^6.0.3",
 		"@semantic-release/git": "^10.0.1",
@@ -47,12 +48,17 @@
 		"vitest": "^4.1.5"
 	},
 	"peerDependencies": {
+		"fuse.js": ">=6.0.0",
 		"react": ">=16.13.1",
 		"react-dom": ">=16.13.1"
 	},
+	"peerDependenciesMeta": {
+		"fuse.js": {
+			"optional": true
+		}
+	},
 	"dependencies": {
-		"@untemps/vocal": "^1.3.0",
-		"fuse.js": "^7.3.0"
+		"@untemps/vocal": "^1.3.0"
 	},
 	"release": {
 		"branches": [

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])
@@ -83,20 +92,23 @@ const Vocal = ({
 
 	const _onResult = useCallback(
 		(event) => {
-			const transcript = Array.from(event?.results ?? [], (segment) => {
+			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.transcript ?? ''
-			}).join('')
+				return { best: best.transcript ?? '', alternatives }
+			})
+			const transcript = segmentData.map((s) => s.best).join('')
 
 			stopTimer()
 			stopRecognition()
-			triggerCommandRef.current(transcript)
+			tryMatchCommand(segmentData, triggerCommandRef.current)
 			propsRef.current.onResult?.(transcript, event)
 		},
 		[stopTimer, stopRecognition]
@@ -122,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

@@ -428,7 +428,92 @@ describe('Vocal', () => {
 		expect(onErrorV1).not.toHaveBeenCalled()
 	})
 
-	it('returns the most confident alternative when multiple alternatives are provided', async () => {
+	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 }))
@@ -444,7 +529,7 @@ describe('Vocal', () => {
 		})
 	})
 
-	it('joins all segments when multiple result segments are provided', async () => {
+	it('joins all segments into the onResult transcript', async () => {
 		const onResult = vi.fn()
 		const recognition = new SpeechRecognitionWrapper()
 		const { getByTestId } = render(getInstance({ __rsInstance: recognition, onResult }))
@@ -459,18 +544,68 @@ describe('Vocal', () => {
 		})
 	})
 
-	it('picks highest-confidence alternative per segment when multi-segment with multi-alternative', async () => {
+	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 { getByTestId } = render(getInstance({ __rsInstance: recognition, onResult }))
+		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: 'good ', confidence: 0.8 }, { transcript: 'bad ', confidence: 0.2 }],
-				[{ transcript: 'day', confidence: 0.95 }, { transcript: 'dey', confidence: 0.3 }],
-			])
-			await waitFor(() => expect(onResult).toHaveBeenCalledWith('good day', expect.anything()))
+			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

@@ -1,7 +1,17 @@
-import { renderHook } from '@testing-library/react'
+import { act, renderHook } from '@testing-library/react'
 
 import useCommands from '../useCommands'
 
+// Static import anchors fuse.js in the module graph so vi.mock intercepts the
+// dynamic import('fuse.js') inside the hook. Without it the dynamic import resolves
+// against the real module before the async mock factory completes.
+import 'fuse.js'
+
+vi.mock('fuse.js', async () => {
+	const actual = await vi.importActual('fuse.js')
+	return actual
+})
+
 describe('useCommands', () => {
 	it('returns triggerCommand function', () => {
 		const triggerCommand = renderHook(() => useCommands())
@@ -41,13 +51,15 @@ describe('useCommands', () => {
 			['Change la bordure en vert', 'Change la bordure en verre de rouge', null],
 			['Change la bordure en vert', 'Change la bordure en violet', null],
 			['Change la bordure en vert', 'Modifie la bordure en violet', null],
-		])('triggers callback mapped to approximate inputs', (command, input, expected) => {
+		])('triggers callback mapped to approximate inputs', async (command, input, expected) => {
 			const commands = {
 				[command]: () => value,
 			}
 			const {
 				result: { current: triggerCommand },
 			} = renderHook(() => useCommands(commands))
+			// Flush the dynamic import microtask
+			await act(async () => {})
 			expect(triggerCommand(input)).toBe(expected)
 		})
 	})
@@ -61,4 +73,43 @@ 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')
+	})
+
+	it('falls back to contains matching when fuse.js is not available', async () => {
+		vi.doMock('fuse.js', () => {
+			throw new Error('fuse.js not installed')
+		})
+		const { default: useCommandsWithoutFuse } = await import('../useCommands')
+		const commands = { 'change color': () => 'matched' }
+		const {
+			result: { current: triggerCommand },
+		} = renderHook(() => useCommandsWithoutFuse(commands))
+		await act(async () => {})
+		expect(triggerCommand('change color')).toBe('matched')
+		vi.doUnmock('fuse.js')
+	})
 })

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,70 @@
-import Fuse from 'fuse.js'
+import { useEffect, useMemo, useRef } from 'react'
 
 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])
+
+	// Lazy-loaded so consumers using only single-word commands incur no bundle cost.
+	const fuseRef = useRef(null)
+
+	useEffect(() => {
+		if (!hasPhraseKeys) {
+			fuseRef.current = null
+			return
+		}
+		import('fuse.js')
+			.then((module) => {
+				const Fuse = module.default ?? module
+				fuseRef.current = new Fuse(keys, { includeScore: true, ignoreLocation: true })
+			})
+			.catch(() => {
+				if (process.env.NODE_ENV !== 'production') {
+					console.warn(
+						'[react-vocal] fuse.js is not installed. Phrase command keys will fall back to exact matching. ' +
+							'Install fuse.js to enable fuzzy matching: npm install fuse.js'
+					)
+				}
+			})
+	}, [hasPhraseKeys, keys])
 
 	const triggerCommand = (input) => {
-		const fuse = new Fuse(Object.keys(commands), { includeScore: true, ignoreLocation: true })
-		const result = fuse.search(input).filter((r) => r.score < precision)
-		if (!!result?.length) {
-			const key = result[0].item.toLowerCase()
-			return commands[key]?.(input)
+		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 fuse = fuseRef.current
+		if (fuse) {
+			const result = fuse.search(input).filter((r) => r.score < precision)
+			if (result?.length) {
+				const key = result[0].item.toLowerCase()
+				return normalized[key]?.(input)
+			}
+		} else {
+			// `k.includes(lInput)` can produce false positives when input is short
+			// (e.g. "rouge" matches "change en rouge"). Accepted tradeoff: this branch
+			// only runs when fuse.js is absent, so degraded precision is expected.
+			const lInput = input.toLowerCase()
+			const match = keys.find((k) => lInput.includes(k) || k.includes(lInput))
+			if (match) return normalized[match]?.(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/vite.config.js

@@ -11,11 +11,12 @@ export default defineConfig({
 			fileName: (format) => ({ es: 'index.es.js', umd: 'index.umd.js', cjs: 'index.js' })[format],
 		},
 		rollupOptions: {
-			external: ['react', 'react-dom'],
+			external: ['react', 'react-dom', 'fuse.js'],
 			output: {
 				globals: {
 					react: 'React',
 					'react-dom': 'ReactDOM',
+					'fuse.js': 'Fuse',
 				},
 			},
 		},

package/vitest.setup.js

@@ -67,6 +67,9 @@ global.SpeechRecognition = vi.fn(function () {
 				handlers.nomatch?.()
 			}
 		}),
+		end: vi.fn(function () {
+			handlers.end?.()
+		}),
 		error: vi.fn(function (err) {
 			handlers.error?.(err)
 		}),