@untemps/react-vocal 2.0.0-beta.1 → 2.0.0-beta.10

package/CHANGELOG.md

@@ -1,3 +1,81 @@
+# [2.0.0-beta.10](https://github.com/untemps/react-vocal/compare/v2.0.0-beta.9...v2.0.0-beta.10) (2026-05-24)
+
+
+### Bug Fixes
+
+* Add aria-hidden to decorative SVG in Icon component ([#148](https://github.com/untemps/react-vocal/issues/148)) ([5e00e34](https://github.com/untemps/react-vocal/commit/5e00e34e991b1a5c1a29a393ac885a76864c601c))
+
+# [2.0.0-beta.9](https://github.com/untemps/react-vocal/compare/v2.0.0-beta.8...v2.0.0-beta.9) (2026-05-24)
+
+
+### Bug Fixes
+
+* Prevent stale Fuse instance in useCommands after async fuse.js import ([#147](https://github.com/untemps/react-vocal/issues/147)) ([a83f06d](https://github.com/untemps/react-vocal/commit/a83f06d73644d1029e735b38dc06c8614470e19e))
+
+# [2.0.0-beta.8](https://github.com/untemps/react-vocal/compare/v2.0.0-beta.7...v2.0.0-beta.8) (2026-05-24)
+
+
+### Features
+
+* Migrate to @untemps/vocal 2.x functional API ([#146](https://github.com/untemps/react-vocal/issues/146)) ([582575f](https://github.com/untemps/react-vocal/commit/582575f391472e0e95b0c793b57c7c3edca71939))
+
+
+### BREAKING CHANGES
+
+* `isSupported` is now a function instead of a boolean snapshot. Consumers must call it as `isSupported()`.
+Migration:
+   // before
+   import { isSupported } from '@untemps/react-vocal'
+   if (isSupported) { ... }
+   // after
+   import { isSupported } from '@untemps/react-vocal'
+   if (isSupported()) { ... }
+The function form is SSR-safe — it returns `false` when `window` is undefined, so consumers no longer need a manual `typeof window` guard before checking support.
+* UMD bundle is no longer published.
+`dist/index.umd.js` is removed from the release artifacts and from the npm tarball. Consumers loading react-vocal via `<script src="…/dist/index.umd.js">` or an AMD loader must migrate to the ES bundle (`dist/index.es.js`) via a module-aware loader (or use a bundler). The CJS bundle (`dist/index.js`) remains available for Node-style require().
+
+# [2.0.0-beta.7](https://github.com/untemps/react-vocal/compare/v2.0.0-beta.6...v2.0.0-beta.7) (2026-05-13)
+
+# [2.0.0-beta.6](https://github.com/untemps/react-vocal/compare/v2.0.0-beta.5...v2.0.0-beta.6) (2026-05-12)
+
+
+### Features
+
+* Add continuous session support ([#118](https://github.com/untemps/react-vocal/issues/118)) ([690ba61](https://github.com/untemps/react-vocal/commit/690ba617746aa28499d7ea2d48751453a652ff5e))
+
+# [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)
+
+
+### Features
+
+* Aggregate all result segments picking highest-confidence alternative ([#113](https://github.com/untemps/react-vocal/issues/113)) ([600600d](https://github.com/untemps/react-vocal/commit/600600dfde457df6fe93974d76d0b48599846082))
+
+# [2.0.0-beta.2](https://github.com/untemps/react-vocal/compare/v2.0.0-beta.1...v2.0.0-beta.2) (2026-05-07)
+
+
+### Bug Fixes
+
+* Stabilize event handlers and fix stale prop closures ([#112](https://github.com/untemps/react-vocal/issues/112)) ([69c5c00](https://github.com/untemps/react-vocal/commit/69c5c00ed73e792b6dd91dd6b294163e1c3d00dc))
+
 # [2.0.0-beta.1](https://github.com/untemps/react-vocal/compare/v1.7.35...v2.0.0-beta.1) (2026-05-05)
 
 

package/README.md

@@ -33,7 +33,7 @@ timeout elapses.
 Some browsers supports the `SpeechRecognition` API but not all the related APIs.  
 For example, browsers on iOS 14.5, the `SpeechGrammar` and `SpeechGrammarList` and `Permissions` APIs are not supported.
 
-Although the lack of `SpeechGrammar` and `SpeechGrammarList` is handled by the underlaying `@untemps/vocal` library, you need to deal with `Permissions` by yourself.
+Although the lack of `SpeechGrammar` and `SpeechGrammarList` is handled by the underlying `@untemps/vocal` library, you need to deal with `Permissions` by yourself.
 
 ## Requirements
 
@@ -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,14 @@ 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). |
+| continuous      | boolean           | false                | Keep the recognition session open after each result. The session accumulates transcript across segments and stops when the button is clicked again or `silenceTimeout` expires. Commands are not evaluated in continuous mode. |
+| silenceTimeout  | number            | null                 | When `continuous` is true, automatically stop the session after this many ms of inactivity following the last recognized result. `null` or `0` disables auto-stop (button click required). |
 | 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                                                         |
@@ -223,6 +237,7 @@ See [fuze.js scoring theory](https://fusejs.io/concepts/scoring-theory.html) for
 | onResult      | func              | null                 | Handler called when a result is recognized                                                      |
 | onError       | func              | null                 | Handler called when an error occurs                                                             |
 | onNoMatch     | func              | null                 | Handler called when no result can be recognized                                                 |
+| signal        | AbortSignal       | null                 | Optional `AbortSignal` propagated to the underlying `start()` call. Aborting it cancels the in-flight start (e.g. while waiting for microphone permission). |
 
 ### `useVocal` hook
 
@@ -286,41 +301,60 @@ const App = () => {
 #### Signature
 
 ```
-useVocal(lang, grammars)
+useVocal(lang, grammars, maxAlternatives, continuous)
 ```
 
-| 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                                          |
+| continuous      | boolean           | false   | Keep the recognition session open after each result                                             |
 
 ---
 
 #### Return value
 
 ```
-const [ref, { start, stop, abort, subscribe, unsubscribe, clean }]
+const [ref, { start, stop, abort, subscribe, unsubscribe, clean, isRecording }]
 ```
 
 | Args        | Type | Description                                          |
 | ----------- | ---- | ---------------------------------------------------- |
-| ref         | Ref  | React ref to the SpeechRecognitionWrapper instance   |
-| start       | func | Function to start the recognition                    |
+| ref         | Ref  | React ref to the underlying `@untemps/vocal` instance |
+| start       | func | Function to start the recognition. Accepts an optional `{ signal }` argument — an `AbortSignal` propagated to the underlying `start()` call. Returns the underlying `vocal.start()` promise (resolves once the session starts, rejects on microphone/permission errors). |
 | stop        | func | Function to stop the recognition                     |
 | abort       | func | Function to abort the recognition                    |
 | subscribe   | func | Function to subscribe to recognition events          |
 | unsubscribe | func | Function to unsubscribe to recognition events        |
 | clean       | func | Function to clean subscription to recognition events |
+| isRecording | bool | Reactive flag mirroring whether a session is active. `true` between `start()` and the next `end`/`error` event. Updated optimistically on `start()` so the UI re-renders at click time. |
+
+#### Cancelling a start in flight
+
+Both `<Vocal signal={...}>` and `useVocal().start({ signal })` accept an `AbortSignal`. Aborting the controller while the browser is still resolving microphone permission cancels the start cleanly — no `start` event is dispatched.
+
+```javascript
+const controller = new AbortController()
+
+// Cancel pending recognition after 2s of waiting for permission
+setTimeout(() => controller.abort(), 2000)
+
+const [, { start }] = useVocal('en-US')
+start({ signal: controller.signal })
+```
 
 ### Browser support flag
 
 #### Basic usage
 
+`isSupported` is a function that returns `true` when the browser supports the Web Speech API (along with the Permissions and MediaDevices APIs that `@untemps/vocal` relies on). It is safe to call during server-side rendering — it returns `false` when `window` is undefined.
+
 ```javascript
 import Vocal, { isSupported } from '@untemps/react-vocal'
 
 const App = () => {
-	return isSupported ? <Vocal /> : <p>Your browser does not support Web Speech API</p>
+	return isSupported() ? <Vocal /> : <p>Your browser does not support Web Speech API</p>
 }
 ```