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

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+# [2.0.0-beta.5](https://github.com/untemps/react-vocal/compare/v2.0.0-beta.4...v2.0.0-beta.5) (2026-05-11)
+
+
+### Features
+
+* Make fuse.js an optional peer dependency ([#117](https://github.com/untemps/react-vocal/issues/117)) ([a1c2a33](https://github.com/untemps/react-vocal/commit/a1c2a337f8d4ba4729c81f0a9b8664bcf914755f))
+
+
+### BREAKING CHANGES
+
+* fuse.js must now be installed separately to enable fuzzy matching for phrase commands.
+
+# [2.0.0-beta.4](https://github.com/untemps/react-vocal/compare/v2.0.0-beta.3...v2.0.0-beta.4) (2026-05-10)
+
+
+### Features
+
+* Per-segment command matching, maxAlternatives, and exact lookup ([39b6370](https://github.com/untemps/react-vocal/commit/39b63701b2a15c058b5ae510be8ad4b4437d6763))
+
 # [2.0.0-beta.3](https://github.com/untemps/react-vocal/compare/v2.0.0-beta.2...v2.0.0-beta.3) (2026-05-07)
 
 

package/README.md

@@ -46,6 +46,14 @@ Although the lack of `SpeechGrammar` and `SpeechGrammarList` is handled by the u
 yarn add @untemps/react-vocal
 ```
 
+Fuzzy matching for phrase commands requires [fuse.js](https://fusejs.io/) as an optional peer dependency:
+
+```bash
+yarn add fuse.js
+```
+
+Without fuse.js, phrase commands fall back to case-insensitive exact matching. Single-word commands always use exact matching and never require fuse.js.
+
 ## Usage
 
 ### `Vocal` component
@@ -192,15 +200,17 @@ const commands = {
 
 The component utilizes a special hook called `useCommands` to respond to the commands.  
 The hook performs a fuzzy search to match approximate commands if needed. This allows to fix accidental typos or approximate recognition results.  
-To do so the hook uses [fuse.js](https://fusejs.io/) which implements an algorithm to find strings that are approximately equal to a given input. The score precision that distinguishes acceptable command-to-callback mapping from negative matching can be customized in the hook instantiantion.
+To do so the hook uses [fuse.js](https://fusejs.io/) which implements an algorithm to find strings that are approximately equal to a given input. The score precision that distinguishes acceptable command-to-callback mapping from negative matching can be customized in the hook instantiation.
 
-```javascript
-useCommands(commands, threshold) // threshold is the limit not to exceed to be considered a match
-```
+fuse.js is an optional peer dependency — install it separately to enable fuzzy matching (see [Installation](#installation)). Without it, phrase commands fall back to case-insensitive exact matching.
+
+**Single-word command keys** (e.g. `rouge`, `submit`) use exact case-insensitive lookup. When the recognition returns a multi-word transcript, each word is tried individually so a command fires even when embedded in a phrase (e.g. _"je veux du rouge"_ triggers `rouge`).
+
+**Phrase command keys** (e.g. `'Change the background color'`) use [fuse.js](https://fusejs.io/) fuzzy matching. The `precision` prop controls the Fuse.js score threshold (default `0.4` — lower is stricter).
 
-See [fuze.js scoring theory](https://fusejs.io/concepts/scoring-theory.html) for more details.
+**Homophone tolerance** is achieved via `maxAlternatives`: by setting it to 3–5, the speech engine returns several transcription candidates per segment. The correct word (e.g. _vert_) may appear as a secondary alternative when the primary is a homophone (e.g. _verre_), and will still trigger the command.
 
-> :warning: **The `Vocal` component doesn't expose that score yet.** For now on you have to deal with the default value (*0.4*)
+**At most one command fires per utterance.** Alternatives and segments are scanned in order and matching stops at the first hit, so a single recognition event can trigger at most one command callback.
 
 ---
 
@@ -208,10 +218,12 @@ See [fuze.js scoring theory](https://fusejs.io/concepts/scoring-theory.html) for
 
 | Props         | Type              | Default              | Description                                                                                     |
 | ------------- | ----------------- | -------------------- | ----------------------------------------------------------------------------------------------- |
-| commands      | object            | null                 | Callbacks to be triggered when specified commands are detected by the recognition               |
-| lang          | string            | 'en-US'              | Language understood by the recognition [BCP 47 language tag](https://tools.ietf.org/html/bcp47) |
-| grammars      | SpeechGrammarList | null                 | Grammars understood by the recognition [JSpeech Grammar Format](https://www.w3.org/TR/jsgf/)    |
-| timeout       | number            | 3000                 | Time in ms to wait before discarding the recognition                                            |
+| commands        | object            | null                 | Callbacks to be triggered when specified commands are detected by the recognition               |
+| lang            | string            | 'en-US'              | Language understood by the recognition [BCP 47 language tag](https://tools.ietf.org/html/bcp47) |
+| grammars        | SpeechGrammarList | null                 | Grammars understood by the recognition [JSpeech Grammar Format](https://www.w3.org/TR/jsgf/)    |
+| timeout         | number            | 3000                 | Time in ms to wait before discarding the recognition                                            |
+| precision       | number            | 0.4                  | Fuse.js score threshold for **phrase** command keys only (lower = stricter). Single-word commands always use exact lookup. |
+| maxAlternatives | number            | 1                    | Maximum number of recognition alternatives per segment. Setting this to 3–5 lets the engine surface the correct word as a secondary transcript, which is useful for handling homophones (e.g. _vert_ / _verre_ in French). |
 | style         | object            | null                 | Styles of the root element if className is not specified                                        |
 | className     | string            | null                 | Class of the root element                                                                       |
 | ariaLabel     | string            | 'start recognition'  | Accessible label for the default button                                                         |
@@ -286,13 +298,14 @@ const App = () => {
 #### Signature
 
 ```
-useVocal(lang, grammars)
+useVocal(lang, grammars, maxAlternatives)
 ```
 
-| Args     | Type              | Default | Description                                                                                     |
-| -------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- |
-| lang     | string            | 'en-US' | Language understood by the recognition [BCP 47 language tag](https://tools.ietf.org/html/bcp47) |
-| grammars | SpeechGrammarList | null    | Grammars understood by the recognition [JSpeech Grammar Format](https://www.w3.org/TR/jsgf/)    |
+| Args            | Type              | Default | Description                                                                                     |
+| --------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- |
+| lang            | string            | 'en-US' | Language understood by the recognition [BCP 47 language tag](https://tools.ietf.org/html/bcp47) |
+| grammars        | SpeechGrammarList | null    | Grammars understood by the recognition [JSpeech Grammar Format](https://www.w3.org/TR/jsgf/)    |
+| maxAlternatives | number            | 1       | Maximum number of recognition alternatives per segment                                          |
 
 ---
 

package/dev/src/index.jsx

@@ -1,43 +1,56 @@
-import React, { useState } from 'react'
+import React, { useMemo, useState } from 'react'
 import { createRoot } from 'react-dom/client'
 
 import Vocal from '../../src'
 
+const COMMANDS = {
+	rouge: 'red',
+	bleu: 'blue',
+	vert: 'green',
+	jaune: 'yellow',
+}
+
 const App = () => {
 	const [logs, setLogs] = useState('')
 	const [borderColor, setBorderColor] = useState()
 
-	const _log = (value) => setLogs((logs) => `${logs}${logs.length > 0 ? '\n' : ''} ----- ${value}`)
-
-	const _onVocalStart = () => {
-		_log('start')
-	}
-
-	const _onVocalEnd = () => {
-		_log(`end`)
-	}
-
-	const _onVocalResult = (result) => {
-		_log(`result: "${result}"`)
-	}
-
-	const _onVocalError = (e) => {
-		_log(e.message)
-	}
+	const _log = (value) => setLogs((prev) => `${prev}${prev.length > 0 ? '\n' : ''} ----- ${value}`)
+
+	// Memoized to avoid recreating the commands object (and re-indexing useCommands) on every render
+	const commands = useMemo(
+		() =>
+			Object.fromEntries(
+				Object.entries(COMMANDS).map(([key, color]) => [
+					key,
+					(input) => {
+						_log(`command matched: "${input}" → ${color}`)
+						setBorderColor(color)
+					},
+				])
+			),
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+		[]
+	)
 
 	return (
 		<>
 			<Vocal
 				lang="fr"
-				commands={{
-					'Change la bordure en rouge': () => setBorderColor('red'),
-				}}
-				onStart={_onVocalStart}
-				onEnd={_onVocalEnd}
-				onResult={_onVocalResult}
-				onError={_onVocalError}
+				commands={commands}
+				onStart={() => _log('start')}
+				onEnd={() => _log('end')}
+				onResult={(result) => _log(`result: "${result}"`)}
+				onError={(e) => _log(`error: ${e.message}`)}
+				maxAlternatives={3}
 			/>
-			<textarea value={logs} rows={30} disabled style={{ width: '100%', marginTop: 16, borderColor }} />
+			<p style={{ fontSize: 12, color: '#666', margin: '8px 0' }}>
+				Commandes :{' '}
+				{Object.keys(COMMANDS).map((k, i) => (
+					<span key={k}>{i > 0 && ', '}<code>{k}</code></span>
+				))}
+				{' '}— ou dans une phrase (ex : «&nbsp;je veux du vert&nbsp;»)
+			</p>
+			<textarea value={logs} rows={30} disabled style={{ width: '100%', borderColor }} />
 		</>
 	)
 }