@speechos/react 1.0.0 → 1.0.3

package/dist/components/SpeechOSWidget.d.cts

@@ -17,17 +17,14 @@ export interface SpeechOSWidgetProps {
      * 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
+     * Custom z-index for the widget overlay.
+     * Note: This is handled by @speechos/client, not core SDK.
+     * @deprecated Use SpeechOS.init() from @speechos/client with zIndex instead
      */
     zIndex?: number;
     /**
@@ -98,4 +95,4 @@ declare global {
  * }
  * ```
  */
-export declare function SpeechOSWidget({ apiKey, userId, position, host, zIndex, debug, onTranscription, onEdit, onError, onShow, onHide, className, }: SpeechOSWidgetProps): React.ReactNode;
+export declare function SpeechOSWidget({ apiKey, userId, host, zIndex, debug, onTranscription, onEdit, onError, onShow, onHide, className, }: SpeechOSWidgetProps): React.ReactNode;

package/dist/components/SpeechOSWidget.d.ts

@@ -17,17 +17,14 @@ export interface SpeechOSWidgetProps {
      * 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
+     * Custom z-index for the widget overlay.
+     * Note: This is handled by @speechos/client, not core SDK.
+     * @deprecated Use SpeechOS.init() from @speechos/client with zIndex instead
      */
     zIndex?: number;
     /**
@@ -98,4 +95,4 @@ declare global {
  * }
  * ```
  */
-export declare function SpeechOSWidget({ apiKey, userId, position, host, zIndex, debug, onTranscription, onEdit, onError, onShow, onHide, className, }: SpeechOSWidgetProps): React.ReactNode;
+export declare function SpeechOSWidget({ apiKey, userId, host, zIndex, debug, onTranscription, onEdit, onError, onShow, onHide, className, }: SpeechOSWidgetProps): React.ReactNode;

package/dist/context.d.cts

@@ -5,29 +5,49 @@
  * Uses useSyncExternalStore for efficient state synchronization.
  */
 import React, { type ReactNode } from "react";
-import { type SpeechOSConfig, type SpeechOSState, type SpeechOSEventMap, type UnsubscribeFn } from "@speechos/core";
+import { type SpeechOSCoreConfig, type SpeechOSState, type SpeechOSEventMap, type UnsubscribeFn, type CommandDefinition, type CommandResult } from "@speechos/core";
+import type { FormDetectorInterface } from "@speechos/client";
+import type { TextInputHandlerInterface } from "@speechos/client";
 /**
  * Context value exposed by SpeechOSProvider
  */
 export interface SpeechOSContextValue {
     state: SpeechOSState;
     isInitialized: boolean;
-    init: (config: SpeechOSConfig) => void;
+    init: (config: SpeechOSCoreConfig) => void;
     dictate: () => Promise<string>;
     stopDictation: () => Promise<string>;
     edit: (text: string) => Promise<string>;
     stopEdit: () => Promise<string>;
+    command: (commands: CommandDefinition[]) => Promise<CommandResult | null>;
+    stopCommand: () => Promise<CommandResult | null>;
     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>;
+/**
+ * Extended config for React provider
+ * Includes client-specific options like form detection and text input handler
+ */
+export interface SpeechOSReactConfig extends SpeechOSCoreConfig {
+    /** Command definitions for voice command matching */
+    commands?: CommandDefinition[];
+    /** Custom z-index for widget overlay (default: 999999) */
+    zIndex?: number;
+    /**
+     * Form detection behavior:
+     * - true (default): Enable automatic form field detection
+     * - false: Disable automatic detection (manual control only)
+     * - FormDetectorInterface: Custom implementation
+     */
+    formDetection?: boolean | FormDetectorInterface;
+    /**
+     * Custom text input handler for cursor/selection detection and text operations.
+     * Default: handles input, textarea, and contenteditable elements.
+     */
+    textInputHandler?: TextInputHandlerInterface;
+}
 /**
  * Props for SpeechOSProvider
  */
@@ -35,8 +55,9 @@ export interface SpeechOSProviderProps {
     /**
      * Optional initial configuration.
      * If provided, SDK will be initialized automatically.
+     * Supports all core config options plus client-specific options like formDetection.
      */
-    config?: SpeechOSConfig;
+    config?: SpeechOSReactConfig;
     children: ReactNode;
 }
 /**

package/dist/context.d.ts

@@ -5,29 +5,49 @@
  * Uses useSyncExternalStore for efficient state synchronization.
  */
 import React, { type ReactNode } from "react";
-import { type SpeechOSConfig, type SpeechOSState, type SpeechOSEventMap, type UnsubscribeFn } from "@speechos/core";
+import { type SpeechOSCoreConfig, type SpeechOSState, type SpeechOSEventMap, type UnsubscribeFn, type CommandDefinition, type CommandResult } from "@speechos/core";
+import type { FormDetectorInterface } from "@speechos/client";
+import type { TextInputHandlerInterface } from "@speechos/client";
 /**
  * Context value exposed by SpeechOSProvider
  */
 export interface SpeechOSContextValue {
     state: SpeechOSState;
     isInitialized: boolean;
-    init: (config: SpeechOSConfig) => void;
+    init: (config: SpeechOSCoreConfig) => void;
     dictate: () => Promise<string>;
     stopDictation: () => Promise<string>;
     edit: (text: string) => Promise<string>;
     stopEdit: () => Promise<string>;
+    command: (commands: CommandDefinition[]) => Promise<CommandResult | null>;
+    stopCommand: () => Promise<CommandResult | null>;
     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>;
+/**
+ * Extended config for React provider
+ * Includes client-specific options like form detection and text input handler
+ */
+export interface SpeechOSReactConfig extends SpeechOSCoreConfig {
+    /** Command definitions for voice command matching */
+    commands?: CommandDefinition[];
+    /** Custom z-index for widget overlay (default: 999999) */
+    zIndex?: number;
+    /**
+     * Form detection behavior:
+     * - true (default): Enable automatic form field detection
+     * - false: Disable automatic detection (manual control only)
+     * - FormDetectorInterface: Custom implementation
+     */
+    formDetection?: boolean | FormDetectorInterface;
+    /**
+     * Custom text input handler for cursor/selection detection and text operations.
+     * Default: handles input, textarea, and contenteditable elements.
+     */
+    textInputHandler?: TextInputHandlerInterface;
+}
 /**
  * Props for SpeechOSProvider
  */
@@ -35,8 +55,9 @@ export interface SpeechOSProviderProps {
     /**
      * Optional initial configuration.
      * If provided, SDK will be initialized automatically.
+     * Supports all core config options plus client-specific options like formDetection.
      */
-    config?: SpeechOSConfig;
+    config?: SpeechOSReactConfig;
     children: ReactNode;
 }
 /**

package/dist/hooks/index.d.cts

@@ -8,4 +8,5 @@ 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";
+export { useCommand, type UseCommandResult } from "./useCommand.js";
+export { useSpeechOSWidget, type UseSpeechOSWidgetResult } from "./useSpeechOSWidget.js";

package/dist/hooks/index.d.ts

@@ -8,4 +8,5 @@ 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";
+export { useCommand, type UseCommandResult } from "./useCommand.js";
+export { useSpeechOSWidget, type UseSpeechOSWidgetResult } from "./useSpeechOSWidget.js";

package/dist/hooks/useCommand.d.cts

@@ -0,0 +1,73 @@
+/**
+ * useCommand - Simplified hook for voice command workflows
+ *
+ * Provides a simple start/stop interface for voice command matching.
+ */
+import type { CommandDefinition, CommandResult } from "@speechos/core";
+/**
+ * Return type for useCommand hook
+ */
+export interface UseCommandResult {
+    /** Start command listening - begins recording */
+    start: (commands: CommandDefinition[]) => Promise<void>;
+    /** Stop command listening - ends recording and returns matched command */
+    stop: () => Promise<CommandResult | null>;
+    /** Whether currently listening for commands */
+    isListening: boolean;
+    /** Whether processing the command */
+    isProcessing: boolean;
+    /** The matched command result (null if no match or not yet processed) */
+    result: CommandResult | null;
+    /** Any error that occurred */
+    error: string | null;
+    /** Clear the result and error state */
+    clear: () => void;
+}
+/**
+ * Simplified hook for voice command workflows
+ *
+ * Provides an easy-to-use interface for voice command matching
+ * with automatic state management.
+ *
+ * @example
+ * ```tsx
+ * const commands = [
+ *   { name: 'scroll_down', description: 'Scroll the page down' },
+ *   { name: 'open_settings', description: 'Open the settings modal' },
+ *   {
+ *     name: 'search',
+ *     description: 'Search for something',
+ *     arguments: [{ name: 'query', description: 'The search query' }]
+ *   },
+ * ];
+ *
+ * function VoiceCommands() {
+ *   const { start, stop, isListening, isProcessing, result, error } = useCommand();
+ *
+ *   const handleCommand = async () => {
+ *     await start(commands);
+ *   };
+ *
+ *   const handleStop = async () => {
+ *     const matched = await stop();
+ *     if (matched) {
+ *       console.log('Matched command:', matched.name, matched.arguments);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={isListening ? handleStop : handleCommand} disabled={isProcessing}>
+ *         {isListening ? 'Execute' : 'Say Command'}
+ *       </button>
+ *       {isProcessing && <span>Processing...</span>}
+ *       {result && <p>Command: {result.name}</p>}
+ *       {error && <p style={{ color: 'red' }}>{error}</p>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @returns Command controls and state
+ */
+export declare function useCommand(): UseCommandResult;

package/dist/hooks/useCommand.d.ts

@@ -0,0 +1,73 @@
+/**
+ * useCommand - Simplified hook for voice command workflows
+ *
+ * Provides a simple start/stop interface for voice command matching.
+ */
+import type { CommandDefinition, CommandResult } from "@speechos/core";
+/**
+ * Return type for useCommand hook
+ */
+export interface UseCommandResult {
+    /** Start command listening - begins recording */
+    start: (commands: CommandDefinition[]) => Promise<void>;
+    /** Stop command listening - ends recording and returns matched command */
+    stop: () => Promise<CommandResult | null>;
+    /** Whether currently listening for commands */
+    isListening: boolean;
+    /** Whether processing the command */
+    isProcessing: boolean;
+    /** The matched command result (null if no match or not yet processed) */
+    result: CommandResult | null;
+    /** Any error that occurred */
+    error: string | null;
+    /** Clear the result and error state */
+    clear: () => void;
+}
+/**
+ * Simplified hook for voice command workflows
+ *
+ * Provides an easy-to-use interface for voice command matching
+ * with automatic state management.
+ *
+ * @example
+ * ```tsx
+ * const commands = [
+ *   { name: 'scroll_down', description: 'Scroll the page down' },
+ *   { name: 'open_settings', description: 'Open the settings modal' },
+ *   {
+ *     name: 'search',
+ *     description: 'Search for something',
+ *     arguments: [{ name: 'query', description: 'The search query' }]
+ *   },
+ * ];
+ *
+ * function VoiceCommands() {
+ *   const { start, stop, isListening, isProcessing, result, error } = useCommand();
+ *
+ *   const handleCommand = async () => {
+ *     await start(commands);
+ *   };
+ *
+ *   const handleStop = async () => {
+ *     const matched = await stop();
+ *     if (matched) {
+ *       console.log('Matched command:', matched.name, matched.arguments);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={isListening ? handleStop : handleCommand} disabled={isProcessing}>
+ *         {isListening ? 'Execute' : 'Say Command'}
+ *       </button>
+ *       {isProcessing && <span>Processing...</span>}
+ *       {result && <p>Command: {result.name}</p>}
+ *       {error && <p style={{ color: 'red' }}>{error}</p>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @returns Command controls and state
+ */
+export declare function useCommand(): UseCommandResult;

package/dist/hooks/useSpeechOSWidget.d.cts

@@ -0,0 +1,74 @@
+/**
+ * useSpeechOSWidget - Hook for programmatic widget control
+ *
+ * Provides methods to show, hide, and position the SpeechOS widget
+ * without relying on automatic form field detection.
+ */
+/**
+ * Result type for useSpeechOSWidget hook
+ */
+export interface UseSpeechOSWidgetResult {
+    /**
+     * Show widget positioned for a specific element.
+     * On mobile, widget anchors below the element.
+     * On desktop, widget stays at center bottom but tracks element for dictation/edit.
+     */
+    showFor: (element: HTMLElement) => void;
+    /**
+     * Attach widget to persistently track a specific element.
+     * Equivalent to showFor() - widget tracks element until detach() is called.
+     */
+    attachTo: (element: HTMLElement) => void;
+    /**
+     * Detach widget from any attached element.
+     * Returns widget to default positioning (center bottom of screen).
+     */
+    detach: () => void;
+    /**
+     * Show the widget (default position)
+     */
+    show: () => void;
+    /**
+     * Hide the widget
+     */
+    hide: () => void;
+    /**
+     * Whether the widget is currently visible
+     */
+    isVisible: boolean;
+    /**
+     * Whether the widget is currently expanded (showing action bubbles)
+     */
+    isExpanded: boolean;
+    /**
+     * The currently focused/attached element, if any
+     */
+    focusedElement: HTMLElement | null;
+}
+/**
+ * Hook for programmatic widget control
+ *
+ * Use this hook when you want to control the widget manually instead of
+ * relying on automatic form field detection.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { showFor, hide, isVisible } = useSpeechOSWidget();
+ *   const textareaRef = useRef<HTMLTextAreaElement>(null);
+ *
+ *   return (
+ *     <div>
+ *       <textarea ref={textareaRef} />
+ *       <button onClick={() => showFor(textareaRef.current!)}>
+ *         Enable Voice Input
+ *       </button>
+ *       {isVisible && (
+ *         <button onClick={hide}>Hide Widget</button>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useSpeechOSWidget(): UseSpeechOSWidgetResult;

package/dist/hooks/useSpeechOSWidget.d.ts

@@ -0,0 +1,74 @@
+/**
+ * useSpeechOSWidget - Hook for programmatic widget control
+ *
+ * Provides methods to show, hide, and position the SpeechOS widget
+ * without relying on automatic form field detection.
+ */
+/**
+ * Result type for useSpeechOSWidget hook
+ */
+export interface UseSpeechOSWidgetResult {
+    /**
+     * Show widget positioned for a specific element.
+     * On mobile, widget anchors below the element.
+     * On desktop, widget stays at center bottom but tracks element for dictation/edit.
+     */
+    showFor: (element: HTMLElement) => void;
+    /**
+     * Attach widget to persistently track a specific element.
+     * Equivalent to showFor() - widget tracks element until detach() is called.
+     */
+    attachTo: (element: HTMLElement) => void;
+    /**
+     * Detach widget from any attached element.
+     * Returns widget to default positioning (center bottom of screen).
+     */
+    detach: () => void;
+    /**
+     * Show the widget (default position)
+     */
+    show: () => void;
+    /**
+     * Hide the widget
+     */
+    hide: () => void;
+    /**
+     * Whether the widget is currently visible
+     */
+    isVisible: boolean;
+    /**
+     * Whether the widget is currently expanded (showing action bubbles)
+     */
+    isExpanded: boolean;
+    /**
+     * The currently focused/attached element, if any
+     */
+    focusedElement: HTMLElement | null;
+}
+/**
+ * Hook for programmatic widget control
+ *
+ * Use this hook when you want to control the widget manually instead of
+ * relying on automatic form field detection.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { showFor, hide, isVisible } = useSpeechOSWidget();
+ *   const textareaRef = useRef<HTMLTextAreaElement>(null);
+ *
+ *   return (
+ *     <div>
+ *       <textarea ref={textareaRef} />
+ *       <button onClick={() => showFor(textareaRef.current!)}>
+ *         Enable Voice Input
+ *       </button>
+ *       {isVisible && (
+ *         <button onClick={hide}>Hide Widget</button>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useSpeechOSWidget(): UseSpeechOSWidgetResult;