@speechos/react 1.0.0

package/dist/index.cjs

@@ -0,0 +1,550 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const react = __toESM(require("react"));
+const __speechos_core = __toESM(require("@speechos/core"));
+const react_jsx_runtime = __toESM(require("react/jsx-runtime"));
+
+//#region src/context.tsx
+const SpeechOSContext = (0, react.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 = (0, react.useSyncExternalStore)((0, react.useCallback)((onStoreChange) => {
+		return __speechos_core.state.subscribe(onStoreChange);
+	}, []), (0, react.useCallback)(() => __speechos_core.state.getState(), []), (0, react.useCallback)(() => __speechos_core.state.getState(), []));
+	const isInitialized = __speechos_core.speechOS.isInitialized();
+	if (config && !isInitialized) __speechos_core.speechOS.init(config);
+	const contextValue = (0, react.useMemo)(() => {
+		return {
+			state: currentState,
+			isInitialized: __speechos_core.speechOS.isInitialized(),
+			init: (cfg) => __speechos_core.speechOS.init(cfg),
+			dictate: () => __speechos_core.speechOS.dictate(),
+			stopDictation: () => __speechos_core.speechOS.stopDictation(),
+			edit: (text) => __speechos_core.speechOS.edit(text),
+			stopEdit: () => __speechos_core.speechOS.stopEdit(),
+			cancel: () => __speechos_core.speechOS.cancel(),
+			connect: () => __speechos_core.speechOS.connect(),
+			disconnect: () => __speechos_core.speechOS.disconnect(),
+			enableMicrophone: () => __speechos_core.speechOS.enableMicrophone(),
+			waitUntilReady: () => __speechos_core.speechOS.waitUntilReady(),
+			stopAndGetTranscript: () => __speechos_core.speechOS.stopAndGetTranscript(),
+			stopAndEdit: (originalText) => __speechos_core.speechOS.stopAndEdit(originalText),
+			on: (event, callback) => __speechos_core.events.on(event, callback),
+			off: (event, callback) => {
+				console.warn("SpeechOS: Use the unsubscribe function returned by on() instead of off()");
+			}
+		};
+	}, [currentState]);
+	return /* @__PURE__ */ (0, react_jsx_runtime.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 = (0, react.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) {
+	(0, react.useEffect)(() => {
+		const unsubscribe = __speechos_core.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] = (0, react.useState)(null);
+	const [error, setError] = (0, react.useState)(null);
+	const isRecording = state$1.recordingState === "recording";
+	const isProcessing = state$1.recordingState === "processing";
+	const start = (0, react.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 = (0, react.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 = (0, react.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] = (0, react.useState)(null);
+	const [result, setResult] = (0, react.useState)(null);
+	const [error, setError] = (0, react.useState)(null);
+	const isEditing = state$1.recordingState === "recording" && state$1.activeAction === "edit";
+	const isProcessing = state$1.recordingState === "processing";
+	const start = (0, react.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 = (0, react.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 = (0, react.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 = (0, react.useCallback)(async () => {
+		await contextConnect();
+	}, [contextConnect]);
+	const waitUntilReady = (0, react.useCallback)(async () => {
+		await contextWaitUntilReady();
+	}, [contextWaitUntilReady]);
+	const enableMicrophone = (0, react.useCallback)(async () => {
+		await contextEnableMicrophone();
+	}, [contextEnableMicrophone]);
+	const getTranscript = (0, react.useCallback)(async () => {
+		return await stopAndGetTranscript();
+	}, [stopAndGetTranscript]);
+	const getEdit = (0, react.useCallback)(async (originalText) => {
+		return await stopAndEdit(originalText);
+	}, [stopAndEdit]);
+	const disconnect = (0, react.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 = (0, react.useRef)(null);
+	const widgetRef = (0, react.useRef)(null);
+	const { init, isInitialized } = useSpeechOSContext();
+	(0, react.useEffect)(() => {
+		if (!isInitialized && apiKey) init({
+			apiKey,
+			userId,
+			host,
+			position,
+			zIndex,
+			debug
+		});
+	}, [
+		isInitialized,
+		init,
+		apiKey,
+		userId,
+		host,
+		position,
+		zIndex,
+		debug
+	]);
+	(0, react.useEffect)(() => {
+		const unsubscribers = [];
+		if (onTranscription) unsubscribers.push(__speechos_core.events.on("transcription:inserted", (payload) => {
+			onTranscription(payload.text, payload.element);
+		}));
+		if (onEdit) unsubscribers.push(__speechos_core.events.on("edit:applied", (payload) => {
+			onEdit(payload.editedContent, payload.originalContent, payload.element);
+		}));
+		if (onError) unsubscribers.push(__speechos_core.events.on("error", (payload) => {
+			onError(payload);
+		}));
+		if (onShow) unsubscribers.push(__speechos_core.events.on("widget:show", () => {
+			onShow();
+		}));
+		if (onHide) unsubscribers.push(__speechos_core.events.on("widget:hide", () => {
+			onHide();
+		}));
+		return () => {
+			unsubscribers.forEach((unsub) => unsub());
+		};
+	}, [
+		onTranscription,
+		onEdit,
+		onError,
+		onShow,
+		onHide
+	]);
+	(0, react.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__ */ (0, react_jsx_runtime.jsx)("div", {
+		ref: containerRef,
+		className,
+		style: { display: "contents" }
+	});
+}
+
+//#endregion
+//#region src/index.ts
+const VERSION = "0.1.0";
+
+//#endregion
+exports.SpeechOSContext = SpeechOSContext;
+exports.SpeechOSProvider = SpeechOSProvider;
+exports.SpeechOSWidget = SpeechOSWidget;
+exports.VERSION = VERSION;
+exports.useDictation = useDictation;
+exports.useEdit = useEdit;
+exports.useSpeechOS = useSpeechOS;
+exports.useSpeechOSContext = useSpeechOSContext;
+exports.useSpeechOSEvents = useSpeechOSEvents;
+exports.useSpeechOSState = useSpeechOSState;
+exports.useTranscription = useTranscription;

package/dist/index.d.cts

@@ -0,0 +1,59 @@
+/**
+ * @speechos/react
+ *
+ * React hooks and components for SpeechOS voice integration.
+ *
+ * @example Basic usage with widget
+ * ```tsx
+ * import { SpeechOSProvider, SpeechOSWidget } from '@speechos/react';
+ * import '@speechos/client'; // Registers Web Component
+ *
+ * function App() {
+ *   return (
+ *     <SpeechOSProvider config={{ apiKey: 'your-key' }}>
+ *       <MyForm />
+ *       <SpeechOSWidget
+ *         onTranscription={(text) => console.log(text)}
+ *       />
+ *     </SpeechOSProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example Hook-based usage
+ * ```tsx
+ * import { SpeechOSProvider, useDictation } from '@speechos/react';
+ *
+ * function VoiceInput() {
+ *   const { start, stop, isRecording, transcript } = useDictation();
+ *
+ *   return (
+ *     <button onClick={isRecording ? stop : start}>
+ *       {isRecording ? 'Stop' : 'Start'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @example Low-level usage
+ * ```tsx
+ * import { useSpeechOS } from '@speechos/react';
+ *
+ * function CustomUI() {
+ *   const { connect, waitUntilReady, enableMicrophone, stopAndGetTranscript } = useSpeechOS();
+ *
+ *   const handleRecord = async () => {
+ *     await connect();
+ *     await waitUntilReady();
+ *     await enableMicrophone();
+ *     // ... recording ...
+ *     const text = await stopAndGetTranscript();
+ *   };
+ * }
+ * ```
+ */
+export { SpeechOSProvider, SpeechOSContext, useSpeechOSContext, type SpeechOSContextValue, type SpeechOSProviderProps, } from "./context.js";
+export { useSpeechOS, useSpeechOSState, useSpeechOSEvents, useDictation, useEdit, useTranscription, type UseDictationResult, type UseEditResult, type UseTranscriptionResult, } from "./hooks/index.js";
+export { SpeechOSWidget, type SpeechOSWidgetProps } from "./components/index.js";
+export type { SpeechOSConfig, SpeechOSState, SpeechOSAction, SpeechOSEventMap, RecordingState, UnsubscribeFn, } from "@speechos/core";
+export declare const VERSION = "0.1.0";

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @speechos/react
+ *
+ * React hooks and components for SpeechOS voice integration.
+ *
+ * @example Basic usage with widget
+ * ```tsx
+ * import { SpeechOSProvider, SpeechOSWidget } from '@speechos/react';
+ * import '@speechos/client'; // Registers Web Component
+ *
+ * function App() {
+ *   return (
+ *     <SpeechOSProvider config={{ apiKey: 'your-key' }}>
+ *       <MyForm />
+ *       <SpeechOSWidget
+ *         onTranscription={(text) => console.log(text)}
+ *       />
+ *     </SpeechOSProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example Hook-based usage
+ * ```tsx
+ * import { SpeechOSProvider, useDictation } from '@speechos/react';
+ *
+ * function VoiceInput() {
+ *   const { start, stop, isRecording, transcript } = useDictation();
+ *
+ *   return (
+ *     <button onClick={isRecording ? stop : start}>
+ *       {isRecording ? 'Stop' : 'Start'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @example Low-level usage
+ * ```tsx
+ * import { useSpeechOS } from '@speechos/react';
+ *
+ * function CustomUI() {
+ *   const { connect, waitUntilReady, enableMicrophone, stopAndGetTranscript } = useSpeechOS();
+ *
+ *   const handleRecord = async () => {
+ *     await connect();
+ *     await waitUntilReady();
+ *     await enableMicrophone();
+ *     // ... recording ...
+ *     const text = await stopAndGetTranscript();
+ *   };
+ * }
+ * ```
+ */
+export { SpeechOSProvider, SpeechOSContext, useSpeechOSContext, type SpeechOSContextValue, type SpeechOSProviderProps, } from "./context.js";
+export { useSpeechOS, useSpeechOSState, useSpeechOSEvents, useDictation, useEdit, useTranscription, type UseDictationResult, type UseEditResult, type UseTranscriptionResult, } from "./hooks/index.js";
+export { SpeechOSWidget, type SpeechOSWidgetProps } from "./components/index.js";
+export type { SpeechOSConfig, SpeechOSState, SpeechOSAction, SpeechOSEventMap, RecordingState, UnsubscribeFn, } from "@speechos/core";
+export declare const VERSION = "0.1.0";