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

package/package.json

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

package/src/components/Vocal.jsx

@@ -22,8 +22,10 @@ const Vocal = ({
 	lang = 'en-US',
 	grammars = null,
 	timeout = 3000,
+	silenceTimeout = null,
 	precision = 0.4, // Fuse.js score threshold for phrase commands only; single-word commands always use exact lookup
 	maxAlternatives = 1,
+	continuous = false,
 	ariaLabel = 'start recognition',
 	style = null,
 	className = null,
@@ -40,21 +42,31 @@ const Vocal = ({
 	const buttonRef = useRef(null)
 	const [isListening, setIsListening] = useState(false)
 
-	const [, { start, stop, subscribe, unsubscribe }] = useVocal(lang, grammars, maxAlternatives, __rsInstance)
+	const [, { start, stop, subscribe, unsubscribe }] = useVocal(lang, grammars, maxAlternatives, continuous, __rsInstance)
 	const triggerCommand = useCommands(commands, precision)
 
 	const propsRef = useRef({})
 	propsRef.current = { onStart, onEnd, onSpeechStart, onSpeechEnd, onResult, onError, onNoMatch }
 
+	const continuousRef = useRef(continuous)
+	continuousRef.current = continuous
+
+	// In continuous mode, transcript accumulates across segments and is only emitted via onResult on session end
+	const accumulatedRef = useRef({ transcript: '', event: null })
+
 	const triggerCommandRef = useRef(triggerCommand)
 	triggerCommandRef.current = triggerCommand
 
 	const unsubscribeAllRef = useRef(null)
 	const onEndRef = useRef(null)
 
+	const silenceTimeoutRef = useRef(silenceTimeout)
+	silenceTimeoutRef.current = silenceTimeout
+
 	// Breaks the circular dep: _onEnd → useTimeout(handler) → startTimer captures _onEnd
 	const stableTimerCb = useCallback(() => onEndRef.current?.(), [])
 	const [startTimer, stopTimer] = useTimeout(stableTimerCb, timeout)
+	const [startSilenceTimer, stopSilenceTimer] = useTimeout(stableTimerCb, silenceTimeout ?? 0)
 
 	const stopRecognition = useCallback(() => {
 		try {
@@ -107,11 +119,18 @@ const Vocal = ({
 			const transcript = segmentData.map((s) => s.best).join('')
 
 			stopTimer()
-			stopRecognition()
-			tryMatchCommand(segmentData, triggerCommandRef.current)
-			propsRef.current.onResult?.(transcript, event)
+			if (continuousRef.current) {
+				// Accumulate — onResult fires once at session end, not after each segment
+				accumulatedRef.current.transcript = transcript
+				accumulatedRef.current.event = event
+				if (silenceTimeoutRef.current > 0) startSilenceTimer()
+			} else {
+				tryMatchCommand(segmentData, triggerCommandRef.current)
+				stopRecognition()
+				propsRef.current.onResult?.(transcript, event)
+			}
 		},
-		[stopTimer, stopRecognition]
+		[stopTimer, startSilenceTimer, stopRecognition]
 	)
 
 	const _onError = useCallback(
@@ -134,14 +153,20 @@ const Vocal = ({
 	const _onEnd = useCallback(
 		(e) => {
 			stopTimer()
+			stopSilenceTimer()
 			try {
 				stopRecognition()
 				unsubscribeAllRef.current?.()
+				if (continuousRef.current && accumulatedRef.current.transcript) {
+					propsRef.current.onResult?.(accumulatedRef.current.transcript, accumulatedRef.current.event)
+					accumulatedRef.current.transcript = ''
+					accumulatedRef.current.event = null
+				}
 			} finally {
 				propsRef.current.onEnd?.(e)
 			}
 		},
-		[stopTimer, stopRecognition]
+		[stopTimer, stopSilenceTimer, stopRecognition]
 	)
 
 	onEndRef.current = _onEnd
@@ -164,13 +189,16 @@ const Vocal = ({
 
 	const startRecognition = useCallback(() => {
 		try {
+			accumulatedRef.current.transcript = ''
+			accumulatedRef.current.event = null
+			stopSilenceTimer()
 			setIsListening(true)
 			Object.entries(HANDLERS).forEach(([event, fn]) => subscribe(event, fn))
 			start()
 		} catch (error) {
 			_onError(error)
 		}
-	}, [HANDLERS, subscribe, start, _onError])
+	}, [HANDLERS, subscribe, start, stopSilenceTimer, _onError])
 
 	const _onFocus = () => {
 		if (!className && outlineStyle) {
@@ -188,8 +216,8 @@ const Vocal = ({
 		<button
 			data-testid="__vocal-root__"
 			ref={buttonRef}
-			role="button"
 			aria-label={ariaLabel}
+			aria-pressed={isListening}
 			style={
 				className
 					? null
@@ -199,14 +227,14 @@ const Vocal = ({
 							backgroundColor: 'transparent', // `background: none` shorthand resets all sub-properties; jsdom 29 + jest-dom v6 don't reflect that correctly via getComputedStyle
 							border: 'none',
 							padding: 0,
-							cursor: !isListening ? 'pointer' : 'default',
+							cursor: !continuous && isListening ? 'default' : 'pointer',
 							...style,
 					  }
 			}
 			className={className}
 			onFocus={_onFocus}
 			onBlur={_onBlur}
-			onClick={startRecognition}
+			onClick={isListening ? stopRecognition : startRecognition}
 		>
 			<Icon isActive={isListening} color="#aaa" />
 		</button>

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

@@ -99,12 +99,24 @@ describe('Vocal', () => {
 		expect(getByTestId('__vocal-root__')).toHaveStyle({ cursor: 'pointer' })
 	})
 
-	it('renders default cursor when listening', () => {
+	it('renders default cursor when listening in non-continuous mode', () => {
 		const { getByTestId } = render(getInstance())
 		fireEvent.click(getByTestId('__vocal-root__'))
 		expect(getByTestId('__vocal-root__')).toHaveStyle({ cursor: 'default' })
 	})
 
+	it('renders pointer cursor when listening in continuous mode', () => {
+		const { getByTestId } = render(getInstance({ continuous: true }))
+		fireEvent.click(getByTestId('__vocal-root__'))
+		expect(getByTestId('__vocal-root__')).toHaveStyle({ cursor: 'pointer' })
+	})
+
+	it('sets aria-pressed when listening', () => {
+		const { getByTestId } = render(getInstance())
+		fireEvent.click(getByTestId('__vocal-root__'))
+		expect(getByTestId('__vocal-root__')).toHaveAttribute('aria-pressed', 'true')
+	})
+
 	it('renders outline when focused', () => {
 		const { getByTestId } = render(getInstance())
 		fireEvent.focus(getByTestId('__vocal-root__'))
@@ -145,7 +157,7 @@ describe('Vocal', () => {
 			await waitFor(() => flag)
 
 			recognition.instance.say('Foo')
-			await waitFor(() => expect(callback).toHaveBeenCalledWith('Foo'))
+			await waitFor(() => expect(callback).toHaveBeenCalledWith('Foo', 'foo'))
 		})
 	})
 
@@ -276,7 +288,7 @@ describe('Vocal', () => {
 
 		await act(async () => {
 			fireEvent.click(getByTestId('__vocal-root__'))
-			await waitFor(() => expect(getByTestId('__vocal-root__')).toHaveStyle({ cursor: 'default' }))
+			await waitFor(() => expect(getByTestId('__vocal-root__')).toHaveAttribute('aria-pressed', 'true'))
 		})
 
 		await act(async () => {
@@ -298,7 +310,7 @@ describe('Vocal', () => {
 
 		await act(async () => {
 			fireEvent.click(getByTestId('__vocal-root__'))
-			await waitFor(() => expect(getByTestId('__vocal-root__')).toHaveStyle({ cursor: 'default' }))
+			await waitFor(() => expect(getByTestId('__vocal-root__')).toHaveAttribute('aria-pressed', 'true'))
 		})
 
 		await act(async () => {
@@ -310,7 +322,7 @@ describe('Vocal', () => {
 			await waitFor(() => expect(onEnd).toHaveBeenCalled())
 		})
 
-		expect(getByTestId('__vocal-root__')).toHaveStyle({ cursor: 'pointer' })
+		expect(getByTestId('__vocal-root__')).toHaveAttribute('aria-pressed', 'false')
 	})
 
 	it('calls the updated onResult prop after a re-render during an active session', async () => {
@@ -321,7 +333,7 @@ describe('Vocal', () => {
 
 		await act(async () => {
 			fireEvent.click(getByTestId('__vocal-root__'))
-			await waitFor(() => expect(getByTestId('__vocal-root__')).toHaveStyle({ cursor: 'default' }))
+			await waitFor(() => expect(getByTestId('__vocal-root__')).toHaveAttribute('aria-pressed', 'true'))
 		})
 
 		await act(async () => {
@@ -344,7 +356,7 @@ describe('Vocal', () => {
 
 		await act(async () => {
 			fireEvent.click(getByTestId('__vocal-root__'))
-			await waitFor(() => expect(getByTestId('__vocal-root__')).toHaveStyle({ cursor: 'default' }))
+			await waitFor(() => expect(getByTestId('__vocal-root__')).toHaveAttribute('aria-pressed', 'true'))
 		})
 
 		await act(async () => {
@@ -367,7 +379,7 @@ describe('Vocal', () => {
 
 		await act(async () => {
 			fireEvent.click(getByTestId('__vocal-root__'))
-			await waitFor(() => expect(getByTestId('__vocal-root__')).toHaveStyle({ cursor: 'default' }))
+			await waitFor(() => expect(getByTestId('__vocal-root__')).toHaveAttribute('aria-pressed', 'true'))
 		})
 
 		await act(async () => {
@@ -390,7 +402,7 @@ describe('Vocal', () => {
 
 		await act(async () => {
 			fireEvent.click(getByTestId('__vocal-root__'))
-			await waitFor(() => expect(getByTestId('__vocal-root__')).toHaveStyle({ cursor: 'default' }))
+			await waitFor(() => expect(getByTestId('__vocal-root__')).toHaveAttribute('aria-pressed', 'true'))
 		})
 
 		await act(async () => {
@@ -413,7 +425,7 @@ describe('Vocal', () => {
 
 		await act(async () => {
 			fireEvent.click(getByTestId('__vocal-root__'))
-			await waitFor(() => expect(getByTestId('__vocal-root__')).toHaveStyle({ cursor: 'default' }))
+			await waitFor(() => expect(getByTestId('__vocal-root__')).toHaveAttribute('aria-pressed', 'true'))
 		})
 
 		await act(async () => {
@@ -440,7 +452,7 @@ describe('Vocal', () => {
 				[{ transcript: 'hello', confidence: 0.9 }],
 				[{ transcript: 'world', confidence: 0.8 }],
 			])
-			await waitFor(() => expect(callback).toHaveBeenCalledWith('hello'))
+			await waitFor(() => expect(callback).toHaveBeenCalledWith('hello', 'hello'))
 		})
 	})
 
@@ -456,7 +468,7 @@ describe('Vocal', () => {
 				[{ transcript: 'hello', confidence: 0.9 }],
 				[{ transcript: 'world', confidence: 0.8 }],
 			])
-			await waitFor(() => expect(callback).toHaveBeenCalledWith('world'))
+			await waitFor(() => expect(callback).toHaveBeenCalledWith('world', 'world'))
 		})
 	})
 
@@ -491,7 +503,7 @@ describe('Vocal', () => {
 				[{ transcript: 'hello', confidence: 0.9 }],
 				[{ transcript: 'world', confidence: 0.8 }],
 			])
-			await waitFor(() => expect(callbackHello).toHaveBeenCalledWith('hello'))
+			await waitFor(() => expect(callbackHello).toHaveBeenCalledWith('hello', 'hello'))
 		})
 
 		expect(callbackWorld).not.toHaveBeenCalled()
@@ -553,7 +565,7 @@ describe('Vocal', () => {
 		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'))
+			await waitFor(() => expect(callback).toHaveBeenCalledWith('rouge', 'rouge'))
 		})
 	})
 
@@ -570,7 +582,7 @@ describe('Vocal', () => {
 				{ transcript: 'verre', confidence: 0.9 },
 				{ transcript: 'vert', confidence: 0.7 },
 			]])
-			await waitFor(() => expect(callback).toHaveBeenCalledWith('vert'))
+			await waitFor(() => expect(callback).toHaveBeenCalledWith('vert', 'vert'))
 		})
 	})
 
@@ -608,4 +620,129 @@ describe('Vocal', () => {
 			await waitFor(() => expect(onEnd).toHaveBeenCalled())
 		})
 	})
+
+	describe('Continuous sessions', () => {
+		it('keeps session active after first result without firing onResult', async () => {
+			const onResult = vi.fn()
+			const recognition = new SpeechRecognitionWrapper()
+			const { getByTestId } = render(getInstance({ __rsInstance: recognition, onResult, continuous: true }))
+
+			await act(async () => {
+				fireEvent.click(getByTestId('__vocal-root__'))
+			})
+
+			await act(async () => {
+				recognition.instance.say('Foo')
+			})
+
+			expect(onResult).not.toHaveBeenCalled()
+			expect(getByTestId('__vocal-root__')).toHaveAttribute('aria-pressed', 'true')
+		})
+
+		it('fires onResult once at session end with full accumulated transcript', async () => {
+			const onResult = vi.fn()
+			const onEnd = vi.fn()
+			const recognition = new SpeechRecognitionWrapper()
+			const { getByTestId } = render(
+				getInstance({ __rsInstance: recognition, onResult, onEnd, continuous: true })
+			)
+
+			await act(async () => {
+				fireEvent.click(getByTestId('__vocal-root__'))
+			})
+
+			await act(async () => {
+				recognition.instance.say('Hello')
+			})
+
+			await act(async () => {
+				recognition.instance.say(' world')
+			})
+
+			expect(onResult).not.toHaveBeenCalled()
+
+			await act(async () => {
+				fireEvent.click(getByTestId('__vocal-root__'))
+				await waitFor(() => expect(onEnd).toHaveBeenCalled())
+			})
+
+			expect(onResult).toHaveBeenCalledTimes(1)
+			expect(onResult).toHaveBeenCalledWith('Hello world', expect.anything())
+		})
+
+		it('stops session on explicit button click while listening', async () => {
+			const onEnd = vi.fn()
+			const recognition = new SpeechRecognitionWrapper()
+			const { getByTestId } = render(getInstance({ __rsInstance: recognition, onEnd, continuous: true }))
+
+			await act(async () => {
+				fireEvent.click(getByTestId('__vocal-root__'))
+			})
+
+			await act(async () => {
+				recognition.instance.say('Foo')
+				await waitFor(() => expect(getByTestId('__vocal-root__')).toHaveAttribute('aria-pressed', 'true'))
+			})
+
+			await act(async () => {
+				fireEvent.click(getByTestId('__vocal-root__'))
+				await waitFor(() => expect(onEnd).toHaveBeenCalled())
+			})
+
+			expect(getByTestId('__vocal-root__')).toHaveAttribute('aria-pressed', 'false')
+		})
+
+		it('does not evaluate commands in continuous mode', async () => {
+			const commandFn = vi.fn()
+			const onEnd = vi.fn()
+			const recognition = new SpeechRecognitionWrapper()
+			const { getByTestId } = render(
+				getInstance({ __rsInstance: recognition, commands: { rouge: commandFn }, onEnd, continuous: true })
+			)
+
+			await act(async () => {
+				fireEvent.click(getByTestId('__vocal-root__'))
+			})
+
+			await act(async () => {
+				recognition.instance.say('rouge')
+				await waitFor(() => expect(getByTestId('__vocal-root__')).toHaveAttribute('aria-pressed', 'true'))
+			})
+
+			await act(async () => {
+				fireEvent.click(getByTestId('__vocal-root__'))
+				await waitFor(() => expect(onEnd).toHaveBeenCalled())
+			})
+
+			expect(commandFn).not.toHaveBeenCalled()
+		})
+
+		it('auto-stops after silenceTimeout ms of inactivity following last result', async () => {
+			vi.useFakeTimers()
+			const onEnd = vi.fn()
+			const onResult = vi.fn()
+			const recognition = new SpeechRecognitionWrapper()
+			const { getByTestId } = render(
+				getInstance({ __rsInstance: recognition, onEnd, onResult, continuous: true, silenceTimeout: 5000 })
+			)
+
+			await act(async () => {
+				fireEvent.click(getByTestId('__vocal-root__'))
+			})
+
+			act(() => {
+				recognition.instance.say('Hello')
+			})
+
+			expect(onEnd).not.toHaveBeenCalled()
+
+			act(() => {
+				vi.advanceTimersByTime(5000)
+			})
+
+			expect(onEnd).toHaveBeenCalled()
+			expect(onResult).toHaveBeenCalledWith('Hello', expect.anything())
+			vi.useRealTimers()
+		})
+	})
 })

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

@@ -4,8 +4,8 @@ exports[`Vocal > matches snapshot 1`] = `
 <DocumentFragment>
   <button
     aria-label="start recognition"
+    aria-pressed="false"
     data-testid="__vocal-root__"
-    role="button"
     style="width: 24px; height: 24px; background-color: transparent; border: medium; padding: 0px; cursor: pointer;"
   >
     <svg

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

@@ -126,7 +126,12 @@ describe('useVocal', () => {
 
 		it('passes maxAlternatives to SpeechRecognitionWrapper constructor', () => {
 			renderHook(() => useVocal('en-US', null, 5))
-			expect(SpeechRecognitionWrapper).toHaveBeenCalledWith({ lang: 'en-US', grammars: null, maxAlternatives: 5 })
+			expect(SpeechRecognitionWrapper).toHaveBeenCalledWith({
+				lang: 'en-US',
+				grammars: null,
+				maxAlternatives: 5,
+				continuous: false,
+			})
 		})
 
 		it('uses custom SpeechRecognition instance', () => {
@@ -135,7 +140,7 @@ describe('useVocal', () => {
 				result: {
 					current: [ref],
 				},
-			} = renderHook(() => useVocal(null, null, 1, foo))
+			} = renderHook(() => useVocal(null, null, 1, false, foo))
 			expect(ref.current).toBe(foo)
 		})
 

package/src/hooks/useCommands.js

@@ -38,33 +38,33 @@ const useCommands = (commands, precision = 0.4) => {
 			})
 	}, [hasPhraseKeys, keys])
 
-	const triggerCommand = (input) => {
+	const triggerCommand = (rawInput) => {
 		if (!keys.length) return null
 
 		if (!hasPhraseKeys) {
-			const words = input.trim().split(/\s+/)
-			const targets = words.length > 1 ? words : [input.trim()]
+			const words = rawInput.trim().split(/\s+/)
+			const targets = words.length > 1 ? words : [rawInput.trim()]
 			for (const w of targets) {
-				const key = w.toLowerCase()
-				if (key in normalized) return normalized[key]?.(w)
+				const commandKey = w.toLowerCase()
+				if (commandKey in normalized) return normalized[commandKey]?.(w, commandKey)
 			}
 			return null
 		}
 
 		const fuse = fuseRef.current
 		if (fuse) {
-			const result = fuse.search(input).filter((r) => r.score < precision)
+			const result = fuse.search(rawInput).filter((r) => r.score < precision)
 			if (result?.length) {
-				const key = result[0].item.toLowerCase()
-				return normalized[key]?.(input)
+				const commandKey = result[0].item.toLowerCase()
+				return normalized[commandKey]?.(rawInput, commandKey)
 			}
 		} 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)
+			const lInput = rawInput.toLowerCase()
+			const commandKey = keys.find((k) => lInput.includes(k) || k.includes(lInput))
+			if (commandKey) return normalized[commandKey]?.(rawInput, commandKey)
 		}
 		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, maxAlternatives = 1, __rsInstance = null) => {
+const useVocal = (lang = 'en-US', grammars = null, maxAlternatives = 1, continuous = false, __rsInstance = null) => {
 	const ref = useRef(null)
 
 	useEffect(() => {
 		if (SpeechRecognitionWrapper.isSupported) {
-			ref.current = __rsInstance || new SpeechRecognitionWrapper({ lang, grammars, maxAlternatives })
+			ref.current = __rsInstance || new SpeechRecognitionWrapper({ lang, grammars, maxAlternatives, continuous })
 			return () => {
 				ref.current.abort()
 				ref.current.cleanup()
 			}
 		}
-	}, [lang, grammars, maxAlternatives, __rsInstance])
+	}, [lang, grammars, maxAlternatives, continuous, __rsInstance])
 
 	const start = useCallback(() => {
 		if (ref.current) {

package/vitest.setup.js

@@ -39,6 +39,7 @@ global.SpeechGrammarList = vi.fn(function () {
 })
 global.SpeechRecognition = vi.fn(function () {
 	const handlers = {}
+	let accumulatedResults = []
 	return {
 		addEventListener: vi.fn(function (type, callback) {
 			handlers[type] = callback
@@ -46,6 +47,7 @@ global.SpeechRecognition = vi.fn(function () {
 		removeEventListener: vi.fn(),
 		dispatchEvent: vi.fn(),
 		start: vi.fn(function () {
+			accumulatedResults = []
 			handlers.start?.()
 		}),
 		stop: vi.fn(function () {
@@ -57,9 +59,13 @@ global.SpeechRecognition = vi.fn(function () {
 		say: vi.fn(function (input) {
 			handlers.speechstart?.()
 
+			const newSegments = Array.isArray(input) ? input : input ? [[{ transcript: input }]] : []
+			const resultIndex = accumulatedResults.length
+			accumulatedResults = [...accumulatedResults, ...newSegments]
+
 			const resultEvent = new Event('result')
-			resultEvent.resultIndex = 0
-			resultEvent.results = Array.isArray(input) ? input : input ? [[{ transcript: input }]] : []
+			resultEvent.resultIndex = resultIndex
+			resultEvent.results = accumulatedResults
 			handlers.speechend?.()
 			if (input) {
 				handlers.result?.(resultEvent)