@speechos/react 1.0.0

package/dist/index.js

@@ -0,0 +1,517 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { events, speechOS, state } from "@speechos/core";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/context.tsx
+const SpeechOSContext = createContext(void 0);
+SpeechOSContext.displayName = "SpeechOSContext";
+/**
+* SpeechOS Provider component
+*
+* Wraps your app to provide SpeechOS context to all child components.
+* Can optionally auto-initialize with a config.
+*
+* @example
+* ```tsx
+* <SpeechOSProvider config={{ apiKey: 'your-key' }}>
+*   <App />
+* </SpeechOSProvider>
+* ```
+*/
+function SpeechOSProvider({ config, children }) {
+	const currentState = useSyncExternalStore(useCallback((onStoreChange) => {
+		return state.subscribe(onStoreChange);
+	}, []), useCallback(() => state.getState(), []), useCallback(() => state.getState(), []));
+	const isInitialized = speechOS.isInitialized();
+	if (config && !isInitialized) speechOS.init(config);
+	const contextValue = useMemo(() => {
+		return {
+			state: currentState,
+			isInitialized: speechOS.isInitialized(),
+			init: (cfg) => speechOS.init(cfg),
+			dictate: () => speechOS.dictate(),
+			stopDictation: () => speechOS.stopDictation(),
+			edit: (text) => speechOS.edit(text),
+			stopEdit: () => speechOS.stopEdit(),
+			cancel: () => speechOS.cancel(),
+			connect: () => speechOS.connect(),
+			disconnect: () => speechOS.disconnect(),
+			enableMicrophone: () => speechOS.enableMicrophone(),
+			waitUntilReady: () => speechOS.waitUntilReady(),
+			stopAndGetTranscript: () => speechOS.stopAndGetTranscript(),
+			stopAndEdit: (originalText) => speechOS.stopAndEdit(originalText),
+			on: (event, callback) => events.on(event, callback),
+			off: (event, callback) => {
+				console.warn("SpeechOS: Use the unsubscribe function returned by on() instead of off()");
+			}
+		};
+	}, [currentState]);
+	return /* @__PURE__ */ jsx(SpeechOSContext.Provider, {
+		value: contextValue,
+		children
+	});
+}
+/**
+* Hook to access the SpeechOS context
+*
+* @throws Error if used outside of SpeechOSProvider
+* @returns The SpeechOS context value
+*/
+function useSpeechOSContext() {
+	const context = useContext(SpeechOSContext);
+	if (context === void 0) throw new Error("useSpeechOSContext must be used within a SpeechOSProvider");
+	return context;
+}
+
+//#endregion
+//#region src/hooks/useSpeechOS.ts
+/**
+* Main hook for accessing the full SpeechOS context
+*
+* @example
+* ```tsx
+* function MyComponent() {
+*   const { state, dictate, cancel, connect, enableMicrophone } = useSpeechOS();
+*
+*   // High-level usage
+*   const handleDictate = async () => {
+*     const text = await dictate();
+*     console.log('Transcribed:', text);
+*   };
+*
+*   // Low-level usage
+*   const handleCustomFlow = async () => {
+*     await connect();
+*     await waitUntilReady();
+*     await enableMicrophone();
+*     // ... custom logic
+*     const text = await stopAndGetTranscript();
+*   };
+* }
+* ```
+*
+* @returns The full SpeechOS context value
+*/
+function useSpeechOS() {
+	return useSpeechOSContext();
+}
+
+//#endregion
+//#region src/hooks/useSpeechOSState.ts
+/**
+* Hook to access just the SpeechOS state
+*
+* Use this when you only need to read state values like
+* isConnected, recordingState, etc. without needing the API methods.
+*
+* @example
+* ```tsx
+* function RecordingIndicator() {
+*   const state = useSpeechOSState();
+*
+*   return (
+*     <div>
+*       {state.recordingState === 'recording' && <span>Recording...</span>}
+*       {state.isConnected && <span>Connected</span>}
+*     </div>
+*   );
+* }
+* ```
+*
+* @returns The current SpeechOS state
+*/
+function useSpeechOSState() {
+	const context = useSpeechOSContext();
+	return context.state;
+}
+
+//#endregion
+//#region src/hooks/useSpeechOSEvents.ts
+/**
+* Hook to subscribe to SpeechOS events
+*
+* Automatically subscribes on mount and unsubscribes on unmount.
+* The callback is stable - changes to it will update the subscription.
+*
+* @example
+* ```tsx
+* function TranscriptionListener() {
+*   useSpeechOSEvents('transcription:complete', (payload) => {
+*     console.log('Transcription received:', payload.text);
+*   });
+*
+*   useSpeechOSEvents('error', (payload) => {
+*     console.error('Error:', payload.message);
+*   });
+*
+*   return <div>Listening for events...</div>;
+* }
+* ```
+*
+* @param event - The event name to subscribe to
+* @param callback - The callback to invoke when the event fires
+* @returns Cleanup function (automatically called on unmount)
+*/
+function useSpeechOSEvents(event, callback) {
+	useEffect(() => {
+		const unsubscribe = events.on(event, callback);
+		return unsubscribe;
+	}, [event, callback]);
+	return () => {};
+}
+
+//#endregion
+//#region src/hooks/useDictation.ts
+/**
+* Simplified hook for dictation workflows
+*
+* Provides an easy-to-use interface for voice-to-text dictation
+* with automatic state management.
+*
+* @example
+* ```tsx
+* function VoiceInput() {
+*   const { start, stop, isRecording, isProcessing, transcript, error } = useDictation();
+*
+*   return (
+*     <div>
+*       <button onClick={isRecording ? stop : start} disabled={isProcessing}>
+*         {isRecording ? 'Stop' : 'Start'} Recording
+*       </button>
+*       {isProcessing && <span>Processing...</span>}
+*       {transcript && <p>You said: {transcript}</p>}
+*       {error && <p style={{ color: 'red' }}>{error}</p>}
+*     </div>
+*   );
+* }
+* ```
+*
+* @returns Dictation controls and state
+*/
+function useDictation() {
+	const { state: state$1, dictate, stopDictation, cancel } = useSpeechOSContext();
+	const [transcript, setTranscript] = useState(null);
+	const [error, setError] = useState(null);
+	const isRecording = state$1.recordingState === "recording";
+	const isProcessing = state$1.recordingState === "processing";
+	const start = useCallback(async () => {
+		setError(null);
+		try {
+			await dictate();
+		} catch (err) {
+			const message = err instanceof Error ? err.message : "Failed to start dictation";
+			setError(message);
+		}
+	}, [dictate]);
+	const stop = useCallback(async () => {
+		try {
+			const result = await stopDictation();
+			setTranscript(result);
+			setError(null);
+			return result;
+		} catch (err) {
+			const message = err instanceof Error ? err.message : "Failed to get transcript";
+			setError(message);
+			throw err;
+		}
+	}, [stopDictation]);
+	const clear = useCallback(() => {
+		setTranscript(null);
+		setError(null);
+	}, []);
+	return {
+		start,
+		stop,
+		isRecording,
+		isProcessing,
+		transcript,
+		error,
+		clear
+	};
+}
+
+//#endregion
+//#region src/hooks/useEdit.ts
+/**
+* Simplified hook for voice editing workflows
+*
+* Provides an easy-to-use interface for voice-based text editing
+* with automatic state management.
+*
+* @example
+* ```tsx
+* function TextEditor() {
+*   const [text, setText] = useState('Hello world');
+*   const { start, stop, isEditing, isProcessing, result, error } = useEdit();
+*
+*   const handleEdit = async () => {
+*     await start(text);
+*   };
+*
+*   const handleStop = async () => {
+*     const edited = await stop();
+*     setText(edited);
+*   };
+*
+*   return (
+*     <div>
+*       <textarea value={text} onChange={(e) => setText(e.target.value)} />
+*       <button onClick={isEditing ? handleStop : handleEdit} disabled={isProcessing}>
+*         {isEditing ? 'Apply Edit' : 'Edit with Voice'}
+*       </button>
+*       {isProcessing && <span>Processing...</span>}
+*       {error && <p style={{ color: 'red' }}>{error}</p>}
+*     </div>
+*   );
+* }
+* ```
+*
+* @returns Edit controls and state
+*/
+function useEdit() {
+	const { state: state$1, edit, stopEdit, cancel } = useSpeechOSContext();
+	const [originalText, setOriginalText] = useState(null);
+	const [result, setResult] = useState(null);
+	const [error, setError] = useState(null);
+	const isEditing = state$1.recordingState === "recording" && state$1.activeAction === "edit";
+	const isProcessing = state$1.recordingState === "processing";
+	const start = useCallback(async (textToEdit) => {
+		setError(null);
+		setOriginalText(textToEdit);
+		try {
+			await edit(textToEdit);
+		} catch (err) {
+			const message = err instanceof Error ? err.message : "Failed to start edit";
+			setError(message);
+		}
+	}, [edit]);
+	const stop = useCallback(async () => {
+		try {
+			const editedResult = await stopEdit();
+			setResult(editedResult);
+			setError(null);
+			return editedResult;
+		} catch (err) {
+			const message = err instanceof Error ? err.message : "Failed to apply edit";
+			setError(message);
+			throw err;
+		}
+	}, [stopEdit]);
+	const clear = useCallback(() => {
+		setOriginalText(null);
+		setResult(null);
+		setError(null);
+	}, []);
+	return {
+		start,
+		stop,
+		isEditing,
+		isProcessing,
+		originalText,
+		result,
+		error,
+		clear
+	};
+}
+
+//#endregion
+//#region src/hooks/useTranscription.ts
+/**
+* Low-level hook for granular transcription control
+*
+* Use this when you need fine-grained control over the LiveKit
+* connection lifecycle. For most use cases, prefer useDictation()
+* or useEdit() which provide simpler interfaces.
+*
+* @example
+* ```tsx
+* function CustomVoiceUI() {
+*   const {
+*     connect,
+*     waitUntilReady,
+*     enableMicrophone,
+*     getTranscript,
+*     disconnect,
+*     isConnected,
+*     isMicEnabled,
+*     recordingState,
+*   } = useTranscription();
+*
+*   const handleRecord = async () => {
+*     // Step 1: Connect to LiveKit
+*     await connect();
+*
+*     // Step 2: Wait for agent to be ready
+*     await waitUntilReady();
+*
+*     // Step 3: Enable microphone
+*     await enableMicrophone();
+*
+*     // ... user speaks ...
+*
+*     // Step 4: Get transcript
+*     const text = await getTranscript();
+*     console.log('Transcribed:', text);
+*
+*     // Step 5: Cleanup
+*     await disconnect();
+*   };
+*
+*   return (
+*     <div>
+*       <p>Connected: {isConnected ? 'Yes' : 'No'}</p>
+*       <p>Mic: {isMicEnabled ? 'On' : 'Off'}</p>
+*       <p>State: {recordingState}</p>
+*       <button onClick={handleRecord}>Record</button>
+*     </div>
+*   );
+* }
+* ```
+*
+* @returns Low-level transcription controls and state
+*/
+function useTranscription() {
+	const { state: state$1, connect: contextConnect, waitUntilReady: contextWaitUntilReady, enableMicrophone: contextEnableMicrophone, stopAndGetTranscript, stopAndEdit, disconnect: contextDisconnect, cancel } = useSpeechOSContext();
+	const connect = useCallback(async () => {
+		await contextConnect();
+	}, [contextConnect]);
+	const waitUntilReady = useCallback(async () => {
+		await contextWaitUntilReady();
+	}, [contextWaitUntilReady]);
+	const enableMicrophone = useCallback(async () => {
+		await contextEnableMicrophone();
+	}, [contextEnableMicrophone]);
+	const getTranscript = useCallback(async () => {
+		return await stopAndGetTranscript();
+	}, [stopAndGetTranscript]);
+	const getEdit = useCallback(async (originalText) => {
+		return await stopAndEdit(originalText);
+	}, [stopAndEdit]);
+	const disconnect = useCallback(async () => {
+		await contextDisconnect();
+	}, [contextDisconnect]);
+	return {
+		connect,
+		waitUntilReady,
+		enableMicrophone,
+		getTranscript,
+		getEdit,
+		disconnect,
+		cancel,
+		isConnected: state$1.isConnected,
+		isMicEnabled: state$1.isMicEnabled,
+		recordingState: state$1.recordingState
+	};
+}
+
+//#endregion
+//#region src/components/SpeechOSWidget.tsx
+/**
+* SpeechOSWidget - React wrapper for the SpeechOS Web Component
+*
+* This component mounts the existing <speechos-widget> Lit Web Component
+* and bridges React props to the Web Component's attributes and events.
+*
+* Note: Requires @speechos/client to be installed and imported somewhere
+* in your app to register the Web Component.
+*
+* @example
+* ```tsx
+* import { SpeechOSProvider, SpeechOSWidget } from '@speechos/react';
+* import '@speechos/client'; // Registers the Web Component
+*
+* function App() {
+*   return (
+*     <SpeechOSProvider>
+*       <MyForm />
+*       <SpeechOSWidget
+*         apiKey="your-key"
+*         onTranscription={(text) => console.log('Transcribed:', text)}
+*         onError={(error) => console.error(error)}
+*       />
+*     </SpeechOSProvider>
+*   );
+* }
+* ```
+*/
+function SpeechOSWidget({ apiKey, userId, position = "bottom-center", host, zIndex, debug, onTranscription, onEdit, onError, onShow, onHide, className }) {
+	const containerRef = useRef(null);
+	const widgetRef = useRef(null);
+	const { init, isInitialized } = useSpeechOSContext();
+	useEffect(() => {
+		if (!isInitialized && apiKey) init({
+			apiKey,
+			userId,
+			host,
+			position,
+			zIndex,
+			debug
+		});
+	}, [
+		isInitialized,
+		init,
+		apiKey,
+		userId,
+		host,
+		position,
+		zIndex,
+		debug
+	]);
+	useEffect(() => {
+		const unsubscribers = [];
+		if (onTranscription) unsubscribers.push(events.on("transcription:inserted", (payload) => {
+			onTranscription(payload.text, payload.element);
+		}));
+		if (onEdit) unsubscribers.push(events.on("edit:applied", (payload) => {
+			onEdit(payload.editedContent, payload.originalContent, payload.element);
+		}));
+		if (onError) unsubscribers.push(events.on("error", (payload) => {
+			onError(payload);
+		}));
+		if (onShow) unsubscribers.push(events.on("widget:show", () => {
+			onShow();
+		}));
+		if (onHide) unsubscribers.push(events.on("widget:hide", () => {
+			onHide();
+		}));
+		return () => {
+			unsubscribers.forEach((unsub) => unsub());
+		};
+	}, [
+		onTranscription,
+		onEdit,
+		onError,
+		onShow,
+		onHide
+	]);
+	useEffect(() => {
+		if (!containerRef.current) return;
+		const isWebComponentRegistered = customElements.get("speechos-widget") !== void 0;
+		if (!isWebComponentRegistered) {
+			console.warn("SpeechOSWidget: <speechos-widget> Web Component is not registered. Make sure to import @speechos/client in your app.");
+			return;
+		}
+		const widget = document.createElement("speechos-widget");
+		widget.setAttribute("position", position);
+		containerRef.current.appendChild(widget);
+		widgetRef.current = widget;
+		return () => {
+			if (widgetRef.current && containerRef.current) {
+				containerRef.current.removeChild(widgetRef.current);
+				widgetRef.current = null;
+			}
+		};
+	}, [position]);
+	return /* @__PURE__ */ jsx("div", {
+		ref: containerRef,
+		className,
+		style: { display: "contents" }
+	});
+}
+
+//#endregion
+//#region src/index.ts
+const VERSION = "0.1.0";
+
+//#endregion
+export { SpeechOSContext, SpeechOSProvider, SpeechOSWidget, VERSION, useDictation, useEdit, useSpeechOS, useSpeechOSContext, useSpeechOSEvents, useSpeechOSState, useTranscription };

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@speechos/react",
+  "version": "1.0.0",
+  "description": "React hooks and components for SpeechOS voice integration",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/speechos-org/speechos.git",
+    "directory": "speechos-client/packages/react"
+  },
+  "homepage": "https://speechos.ai",
+  "bugs": {
+    "url": "https://github.com/speechos-org/speechos/issues"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "speechos",
+    "react",
+    "hooks",
+    "voice",
+    "ai",
+    "speech"
+  ],
+  "author": "SpeechOS",
+  "license": "MIT",
+  "peerDependencies": {
+    "@speechos/client": "^0.2.0",
+    "@speechos/core": "^0.2.0",
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@speechos/client": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "^19.0.7",
+    "happy-dom": "^20.1.0",
+    "react": "^19.0.0",
+    "tsdown": "^0.2.0",
+    "tslib": "^2.8.1",
+    "typescript": "^5.7.3",
+    "vitest": "^4.0.16"
+  },
+  "dependencies": {
+    "@speechos/core": "^0.2.0"
+  }
+}