@speechos/react 1.0.0

package/dist/components/SpeechOSWidget.d.cts

@@ -0,0 +1,101 @@
+/**
+ * SpeechOSWidget - React wrapper for the Lit Web Component widget
+ *
+ * Mounts the existing <speechos-widget> Web Component and forwards
+ * React props as attributes and event handlers.
+ */
+/**
+ * Props for SpeechOSWidget
+ */
+export interface SpeechOSWidgetProps {
+    /**
+     * API key for SpeechOS authentication.
+     * If not provided, must be set via SpeechOSProvider config.
+     */
+    apiKey?: string;
+    /**
+     * Optional user identifier for tracking
+     */
+    userId?: string;
+    /**
+     * Position of the widget on screen
+     * @default 'bottom-center'
+     */
+    position?: "bottom-center" | "bottom-right" | "bottom-left";
+    /**
+     * Backend host URL (for development/testing)
+     */
+    host?: string;
+    /**
+     * Custom z-index for the widget overlay
+     */
+    zIndex?: number;
+    /**
+     * Enable debug logging
+     */
+    debug?: boolean;
+    /**
+     * Callback when transcription is completed and inserted
+     */
+    onTranscription?: (text: string, element: HTMLElement) => void;
+    /**
+     * Callback when edit is completed and applied
+     */
+    onEdit?: (editedText: string, originalText: string, element: HTMLElement) => void;
+    /**
+     * Callback when an error occurs
+     */
+    onError?: (error: {
+        code: string;
+        message: string;
+        source: string;
+    }) => void;
+    /**
+     * Callback when widget becomes visible
+     */
+    onShow?: () => void;
+    /**
+     * Callback when widget is hidden
+     */
+    onHide?: () => void;
+    /**
+     * Additional class name for the container
+     */
+    className?: string;
+}
+declare global {
+    namespace JSX {
+        interface IntrinsicElements {
+            "speechos-widget": React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
+        }
+    }
+}
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+export declare function SpeechOSWidget({ apiKey, userId, position, host, zIndex, debug, onTranscription, onEdit, onError, onShow, onHide, className, }: SpeechOSWidgetProps): React.ReactNode;

package/dist/components/SpeechOSWidget.d.ts

@@ -0,0 +1,101 @@
+/**
+ * SpeechOSWidget - React wrapper for the Lit Web Component widget
+ *
+ * Mounts the existing <speechos-widget> Web Component and forwards
+ * React props as attributes and event handlers.
+ */
+/**
+ * Props for SpeechOSWidget
+ */
+export interface SpeechOSWidgetProps {
+    /**
+     * API key for SpeechOS authentication.
+     * If not provided, must be set via SpeechOSProvider config.
+     */
+    apiKey?: string;
+    /**
+     * Optional user identifier for tracking
+     */
+    userId?: string;
+    /**
+     * Position of the widget on screen
+     * @default 'bottom-center'
+     */
+    position?: "bottom-center" | "bottom-right" | "bottom-left";
+    /**
+     * Backend host URL (for development/testing)
+     */
+    host?: string;
+    /**
+     * Custom z-index for the widget overlay
+     */
+    zIndex?: number;
+    /**
+     * Enable debug logging
+     */
+    debug?: boolean;
+    /**
+     * Callback when transcription is completed and inserted
+     */
+    onTranscription?: (text: string, element: HTMLElement) => void;
+    /**
+     * Callback when edit is completed and applied
+     */
+    onEdit?: (editedText: string, originalText: string, element: HTMLElement) => void;
+    /**
+     * Callback when an error occurs
+     */
+    onError?: (error: {
+        code: string;
+        message: string;
+        source: string;
+    }) => void;
+    /**
+     * Callback when widget becomes visible
+     */
+    onShow?: () => void;
+    /**
+     * Callback when widget is hidden
+     */
+    onHide?: () => void;
+    /**
+     * Additional class name for the container
+     */
+    className?: string;
+}
+declare global {
+    namespace JSX {
+        interface IntrinsicElements {
+            "speechos-widget": React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
+        }
+    }
+}
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+export declare function SpeechOSWidget({ apiKey, userId, position, host, zIndex, debug, onTranscription, onEdit, onError, onShow, onHide, className, }: SpeechOSWidgetProps): React.ReactNode;

package/dist/components/index.d.cts

@@ -0,0 +1,6 @@
+/**
+ * @speechos/react components
+ *
+ * React components for SpeechOS integration.
+ */
+export { SpeechOSWidget, type SpeechOSWidgetProps } from "./SpeechOSWidget.js";

package/dist/components/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @speechos/react components
+ *
+ * React components for SpeechOS integration.
+ */
+export { SpeechOSWidget, type SpeechOSWidgetProps } from "./SpeechOSWidget.js";

package/dist/context.d.cts

@@ -0,0 +1,63 @@
+/**
+ * SpeechOS React Context
+ *
+ * Provides React integration for SpeechOS SDK.
+ * Uses useSyncExternalStore for efficient state synchronization.
+ */
+import React, { type ReactNode } from "react";
+import { type SpeechOSConfig, type SpeechOSState, type SpeechOSEventMap, type UnsubscribeFn } from "@speechos/core";
+/**
+ * Context value exposed by SpeechOSProvider
+ */
+export interface SpeechOSContextValue {
+    state: SpeechOSState;
+    isInitialized: boolean;
+    init: (config: SpeechOSConfig) => void;
+    dictate: () => Promise<string>;
+    stopDictation: () => Promise<string>;
+    edit: (text: string) => Promise<string>;
+    stopEdit: () => Promise<string>;
+    cancel: () => Promise<void>;
+    connect: () => Promise<void>;
+    disconnect: () => Promise<void>;
+    enableMicrophone: () => Promise<void>;
+    waitUntilReady: () => Promise<void>;
+    stopAndGetTranscript: () => Promise<string>;
+    stopAndEdit: (originalText: string) => Promise<string>;
+    on: <K extends keyof SpeechOSEventMap>(event: K, callback: (payload: SpeechOSEventMap[K]) => void) => UnsubscribeFn;
+    off: <K extends keyof SpeechOSEventMap>(event: K, callback: (payload: SpeechOSEventMap[K]) => void) => void;
+}
+declare const SpeechOSContext: React.Context<SpeechOSContextValue | undefined>;
+/**
+ * Props for SpeechOSProvider
+ */
+export interface SpeechOSProviderProps {
+    /**
+     * Optional initial configuration.
+     * If provided, SDK will be initialized automatically.
+     */
+    config?: SpeechOSConfig;
+    children: ReactNode;
+}
+/**
+ * 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>
+ * ```
+ */
+export declare function SpeechOSProvider({ config, children, }: SpeechOSProviderProps): ReactNode;
+/**
+ * Hook to access the SpeechOS context
+ *
+ * @throws Error if used outside of SpeechOSProvider
+ * @returns The SpeechOS context value
+ */
+export declare function useSpeechOSContext(): SpeechOSContextValue;
+export { SpeechOSContext };

package/dist/context.d.ts

@@ -0,0 +1,63 @@
+/**
+ * SpeechOS React Context
+ *
+ * Provides React integration for SpeechOS SDK.
+ * Uses useSyncExternalStore for efficient state synchronization.
+ */
+import React, { type ReactNode } from "react";
+import { type SpeechOSConfig, type SpeechOSState, type SpeechOSEventMap, type UnsubscribeFn } from "@speechos/core";
+/**
+ * Context value exposed by SpeechOSProvider
+ */
+export interface SpeechOSContextValue {
+    state: SpeechOSState;
+    isInitialized: boolean;
+    init: (config: SpeechOSConfig) => void;
+    dictate: () => Promise<string>;
+    stopDictation: () => Promise<string>;
+    edit: (text: string) => Promise<string>;
+    stopEdit: () => Promise<string>;
+    cancel: () => Promise<void>;
+    connect: () => Promise<void>;
+    disconnect: () => Promise<void>;
+    enableMicrophone: () => Promise<void>;
+    waitUntilReady: () => Promise<void>;
+    stopAndGetTranscript: () => Promise<string>;
+    stopAndEdit: (originalText: string) => Promise<string>;
+    on: <K extends keyof SpeechOSEventMap>(event: K, callback: (payload: SpeechOSEventMap[K]) => void) => UnsubscribeFn;
+    off: <K extends keyof SpeechOSEventMap>(event: K, callback: (payload: SpeechOSEventMap[K]) => void) => void;
+}
+declare const SpeechOSContext: React.Context<SpeechOSContextValue | undefined>;
+/**
+ * Props for SpeechOSProvider
+ */
+export interface SpeechOSProviderProps {
+    /**
+     * Optional initial configuration.
+     * If provided, SDK will be initialized automatically.
+     */
+    config?: SpeechOSConfig;
+    children: ReactNode;
+}
+/**
+ * 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>
+ * ```
+ */
+export declare function SpeechOSProvider({ config, children, }: SpeechOSProviderProps): ReactNode;
+/**
+ * Hook to access the SpeechOS context
+ *
+ * @throws Error if used outside of SpeechOSProvider
+ * @returns The SpeechOS context value
+ */
+export declare function useSpeechOSContext(): SpeechOSContextValue;
+export { SpeechOSContext };

package/dist/hooks/index.d.cts

@@ -0,0 +1,11 @@
+/**
+ * @speechos/react hooks
+ *
+ * React hooks for integrating SpeechOS into your application.
+ */
+export { useSpeechOS } from "./useSpeechOS.js";
+export { useSpeechOSState } from "./useSpeechOSState.js";
+export { useSpeechOSEvents } from "./useSpeechOSEvents.js";
+export { useDictation, type UseDictationResult } from "./useDictation.js";
+export { useEdit, type UseEditResult } from "./useEdit.js";
+export { useTranscription, type UseTranscriptionResult } from "./useTranscription.js";

package/dist/hooks/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @speechos/react hooks
+ *
+ * React hooks for integrating SpeechOS into your application.
+ */
+export { useSpeechOS } from "./useSpeechOS.js";
+export { useSpeechOSState } from "./useSpeechOSState.js";
+export { useSpeechOSEvents } from "./useSpeechOSEvents.js";
+export { useDictation, type UseDictationResult } from "./useDictation.js";
+export { useEdit, type UseEditResult } from "./useEdit.js";
+export { useTranscription, type UseTranscriptionResult } from "./useTranscription.js";

package/dist/hooks/useDictation.d.cts

@@ -0,0 +1,51 @@
+/**
+ * useDictation - Simplified hook for dictation workflows
+ *
+ * Provides a simple start/stop interface for voice-to-text dictation.
+ */
+/**
+ * Return type for useDictation hook
+ */
+export interface UseDictationResult {
+    /** Start dictation - begins recording */
+    start: () => Promise<void>;
+    /** Stop dictation - ends recording and returns transcript */
+    stop: () => Promise<string>;
+    /** Whether currently recording */
+    isRecording: boolean;
+    /** Whether processing the recording */
+    isProcessing: boolean;
+    /** The last transcribed text (null if none yet) */
+    transcript: string | null;
+    /** Any error that occurred */
+    error: string | null;
+    /** Clear the transcript and error state */
+    clear: () => void;
+}
+/**
+ * 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
+ */
+export declare function useDictation(): UseDictationResult;

package/dist/hooks/useDictation.d.ts

@@ -0,0 +1,51 @@
+/**
+ * useDictation - Simplified hook for dictation workflows
+ *
+ * Provides a simple start/stop interface for voice-to-text dictation.
+ */
+/**
+ * Return type for useDictation hook
+ */
+export interface UseDictationResult {
+    /** Start dictation - begins recording */
+    start: () => Promise<void>;
+    /** Stop dictation - ends recording and returns transcript */
+    stop: () => Promise<string>;
+    /** Whether currently recording */
+    isRecording: boolean;
+    /** Whether processing the recording */
+    isProcessing: boolean;
+    /** The last transcribed text (null if none yet) */
+    transcript: string | null;
+    /** Any error that occurred */
+    error: string | null;
+    /** Clear the transcript and error state */
+    clear: () => void;
+}
+/**
+ * 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
+ */
+export declare function useDictation(): UseDictationResult;

package/dist/hooks/useEdit.d.cts

@@ -0,0 +1,63 @@
+/**
+ * useEdit - Simplified hook for voice editing workflows
+ *
+ * Provides a simple start/stop interface for voice-based text editing.
+ */
+/**
+ * Return type for useEdit hook
+ */
+export interface UseEditResult {
+    /** Start edit - begins recording voice instructions */
+    start: (textToEdit: string) => Promise<void>;
+    /** Stop edit - ends recording and returns edited text */
+    stop: () => Promise<string>;
+    /** Whether currently recording */
+    isEditing: boolean;
+    /** Whether processing the edit */
+    isProcessing: boolean;
+    /** The original text being edited */
+    originalText: string | null;
+    /** The edited result (null if none yet) */
+    result: string | null;
+    /** Any error that occurred */
+    error: string | null;
+    /** Clear the result and error state */
+    clear: () => void;
+}
+/**
+ * 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
+ */
+export declare function useEdit(): UseEditResult;

package/dist/hooks/useEdit.d.ts

@@ -0,0 +1,63 @@
+/**
+ * useEdit - Simplified hook for voice editing workflows
+ *
+ * Provides a simple start/stop interface for voice-based text editing.
+ */
+/**
+ * Return type for useEdit hook
+ */
+export interface UseEditResult {
+    /** Start edit - begins recording voice instructions */
+    start: (textToEdit: string) => Promise<void>;
+    /** Stop edit - ends recording and returns edited text */
+    stop: () => Promise<string>;
+    /** Whether currently recording */
+    isEditing: boolean;
+    /** Whether processing the edit */
+    isProcessing: boolean;
+    /** The original text being edited */
+    originalText: string | null;
+    /** The edited result (null if none yet) */
+    result: string | null;
+    /** Any error that occurred */
+    error: string | null;
+    /** Clear the result and error state */
+    clear: () => void;
+}
+/**
+ * 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
+ */
+export declare function useEdit(): UseEditResult;

package/dist/hooks/useSpeechOS.d.cts

@@ -0,0 +1,35 @@
+/**
+ * useSpeechOS - Main hook for full SpeechOS context access
+ *
+ * Provides access to all SpeechOS functionality including state,
+ * high-level API (dictate, edit), and low-level API (connect, enableMicrophone).
+ */
+import { type SpeechOSContextValue } from "../context.js";
+/**
+ * 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
+ */
+export declare function useSpeechOS(): SpeechOSContextValue;

package/dist/hooks/useSpeechOS.d.ts

@@ -0,0 +1,35 @@
+/**
+ * useSpeechOS - Main hook for full SpeechOS context access
+ *
+ * Provides access to all SpeechOS functionality including state,
+ * high-level API (dictate, edit), and low-level API (connect, enableMicrophone).
+ */
+import { type SpeechOSContextValue } from "../context.js";
+/**
+ * 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
+ */
+export declare function useSpeechOS(): SpeechOSContextValue;