@poovit-banton/speech-recognition-sdk 1.0.1 → 1.0.3

package/README.md

@@ -1,73 +1,351 @@
-# React + TypeScript + Vite
+# 🎙️ Speech Recognition SDK
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+React SDK สำหรับ Speech Recognition ใช้ Web Speech API พร้อม Widget สวยๆ ใช้งานง่าย
 
-Currently, two official plugins are available:
+![Version](https://img.shields.io/npm/v/@poovit-banton/speech-recognition-sdk)
+![License](https://img.shields.io/npm/l/@poovit-banton/speech-recognition-sdk)
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+## ✨ Features
 
-## React Compiler
+- 🎤 **Speech to Text** - แปลงเสียงพูดเป็นข้อความแบบ Real-time
+- 🌏 **รองรับภาษาไทย** - ตั้งค่า `th-TH` ได้เลย
+- 🎨 **Floating Widget** - ปุ่มลอยพร้อม Modal สวยงาม
+- ⚡ **React Hooks** - ใช้งานง่ายด้วย `useSpeechRecognition`
+- 📦 **TypeScript** - รองรับ TypeScript 100%
+- 🔧 **Customizable** - ปรับแต่งได้ตามต้องการ
 
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+## 📦 Installation
 
-## Expanding the ESLint configuration
+```bash
+npm install @poovit-banton/speech-recognition-sdk
+```
 
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+หรือ
 
-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
+```bash
+yarn add @poovit-banton/speech-recognition-sdk
+```
 
-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
+## 🚀 Quick Start
 
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+### วิธีที่ 1: ใช้ Widget (แนะนำ - ง่ายสุด)
+
+แค่ครอบ App ด้วย `SpeechProvider` แล้วได้ปุ่มลอย + Modal มาเลย!
+
+```tsx
+import { SpeechProvider } from "@poovit-banton/speech-recognition-sdk";
+
+function App() {
+  return (
+    <SpeechProvider
+      showWidget
+      widgetEnabled
+      widgetPosition="bottom-left"
+      config={{ language: "th-TH" }}
+      onGenerate={async (transcript) => {
+        // เรียก API ของคุณตรงนี้
+        const response = await fetch("/api/process", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ text: transcript }),
+        });
+        return await response.json();
+      }}
+      onGenerateComplete={(response) => {
+        console.log("ผลลัพธ์:", response);
+      }}
+    >
+      <YourApp />
+    </SpeechProvider>
+  );
+}
+```
+
+### วิธีที่ 2: ใช้ Hook (ยืดหยุ่นกว่า)
+
+```tsx
+import { useSpeechRecognition } from "@poovit-banton/speech-recognition-sdk";
+
+function MyComponent() {
+  const {
+    transcript, // ข้อความที่พูด
+    isListening, // กำลังฟังอยู่ไหม
+    isSupported, // browser รองรับไหม
+    startListening, // เริ่มฟัง
+    stopListening, // หยุดฟัง
+    resetTranscript, // ล้างข้อความ
+  } = useSpeechRecognition({
+    config: { language: "th-TH" },
+  });
+
+  if (!isSupported) {
+    return <p>Browser ไม่รองรับ Speech Recognition</p>;
+  }
+
+  return (
+    <div>
+      <button onClick={isListening ? stopListening : startListening}>
+        {isListening ? "🛑 หยุด" : "🎤 เริ่มพูด"}
+      </button>
+      <p>{transcript}</p>
+      <button onClick={resetTranscript}>ล้าง</button>
+    </div>
+  );
+}
+```
+
+### วิธีที่ 3: ควบคุม Widget จาก Component
+
+```tsx
+import {
+  SpeechProvider,
+  useSpeechContext,
+} from "@poovit-banton/speech-recognition-sdk";
+
+function App() {
+  return (
+    <SpeechProvider showWidget widgetEnabled>
+      <ControlPanel />
+    </SpeechProvider>
+  );
+}
+
+function ControlPanel() {
+  const { isWidgetEnabled, toggleWidget } = useSpeechContext();
+
+  return (
+    <button onClick={toggleWidget}>
+      {isWidgetEnabled ? "🔇 ปิด" : "🔊 เปิด"} Voice Widget
+    </button>
+  );
+}
 ```
 
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
-
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
-
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
+## 📖 API Reference
+
+### `<SpeechProvider>`
+
+Provider component สำหรับครอบ App
+
+| Prop                 | Type               | Default               | Description                   |
+| -------------------- | ------------------ | --------------------- | ----------------------------- |
+| `showWidget`         | `boolean`          | `false`               | แสดง Floating Widget          |
+| `widgetEnabled`      | `boolean`          | `true`                | เปิด/ปิด Widget               |
+| `widgetPosition`     | `string \| object` | `"bottom-left"`       | ตำแหน่ง Widget                |
+| `widgetButtonSize`   | `number`           | `60`                  | ขนาดปุ่ม (px)                 |
+| `config`             | `object`           | `{}`                  | ตั้งค่า Speech Recognition    |
+| `onGenerate`         | `function`         | -                     | Callback เมื่อกด Generate     |
+| `onGenerateComplete` | `function`         | -                     | Callback เมื่อ Generate เสร็จ |
+| `onGenerateError`    | `function`         | -                     | Callback เมื่อเกิด Error      |
+| `modalTitle`         | `string`           | `"AI Speech-to-Data"` | หัวข้อ Modal                  |
+| `generateButtonText` | `string`           | `"Generate"`          | ข้อความปุ่ม Generate          |
+
+#### Widget Position Options
+
+```tsx
+// Preset positions
+widgetPosition="bottom-left"   // ซ้ายล่าง
+widgetPosition="bottom-right"  // ขวาล่าง
+widgetPosition="top-left"      // ซ้ายบน
+widgetPosition="top-right"     // ขวาบน
+
+// Custom position
+widgetPosition={{ bottom: 20, left: 20 }}
+widgetPosition={{ top: 100, right: 50 }}
+```
+
+### `useSpeechRecognition(options)`
+
+Hook สำหรับใช้งาน Speech Recognition
+
+#### Options
+
+```tsx
+const options = {
+  config: {
+    language: "th-TH", // ภาษา
+    continuous: true, // ฟังต่อเนื่อง
+    interimResults: true, // แสดงผลระหว่างพูด
   },
-])
+  callbacks: {
+    onStart: () => {}, // เริ่มฟัง
+    onEnd: () => {}, // หยุดฟัง
+    onResult: (result) => {}, // ได้ผลลัพธ์
+    onError: (error) => {}, // เกิด error
+  },
+};
+```
+
+#### Return Values
+
+```tsx
+const {
+  // State
+  transcript, // string - ข้อความทั้งหมด
+  interimTranscript, // string - ข้อความระหว่างพูด
+  finalTranscript, // string - ข้อความที่ยืนยันแล้ว
+  isListening, // boolean - กำลังฟังอยู่
+  isSupported, // boolean - browser รองรับ
+  isMicrophoneAvailable, // boolean - มีไมค์
+  error, // string | null - error message
+
+  // Actions
+  startListening, // (config?) => Promise<void>
+  stopListening, // () => void
+  abortListening, // () => void
+  resetTranscript, // () => void
+} = useSpeechRecognition(options);
+```
+
+### `useSpeechContext()`
+
+Hook สำหรับเข้าถึง context ภายใน `SpeechProvider`
+
+```tsx
+const {
+  // ทุกอย่างจาก useSpeechRecognition +
+  isWidgetEnabled, // boolean - Widget เปิดอยู่ไหม
+  setWidgetEnabled, // (enabled: boolean) => void
+  toggleWidget, // () => void
+} = useSpeechContext();
 ```
+
+### Components
+
+| Component             | Description             |
+| --------------------- | ----------------------- |
+| `<SpeechWidget>`      | Floating button + Modal |
+| `<SpeechButton>`      | ปุ่ม Microphone         |
+| `<SpeechModal>`       | Modal สำหรับพูด         |
+| `<TranscriptDisplay>` | แสดงข้อความ             |
+
+## 🌍 Supported Languages
+
+```tsx
+// ตั้งค่าภาษาใน config
+config={{ language: 'th-TH' }}
+```
+
+| Code    | Language     |
+| ------- | ------------ |
+| `th-TH` | ไทย          |
+| `en-US` | English (US) |
+| `en-GB` | English (UK) |
+| `zh-CN` | 中文 (简体)  |
+| `zh-TW` | 中文 (繁體)  |
+| `ja-JP` | 日本語       |
+| `ko-KR` | 한국어       |
+| `vi-VN` | Tiếng Việt   |
+
+## 🌐 Browser Support
+
+| Browser | Support          |
+| ------- | ---------------- |
+| Chrome  | ✅ Full          |
+| Edge    | ✅ Full          |
+| Safari  | ⚠️ Partial       |
+| Firefox | ❌ Not supported |
+
+> ⚠️ Web Speech API ไม่รองรับทุก browser ควรเช็ค `isSupported` ก่อนใช้งาน
+
+## 📝 Example: Full Integration
+
+```tsx
+import React, { useState } from "react";
+import {
+  SpeechProvider,
+  useSpeechContext,
+} from "@poovit-banton/speech-recognition-sdk";
+
+// Main App
+function App() {
+  const [results, setResults] = useState<string[]>([]);
+
+  const handleGenerate = async (transcript: string) => {
+    // เรียก API
+    const response = await fetch("/api/ai/process", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ text: transcript }),
+    });
+
+    const data = await response.json();
+    return data.result;
+  };
+
+  return (
+    <SpeechProvider
+      showWidget
+      widgetEnabled
+      widgetPosition="bottom-left"
+      config={{ language: "th-TH", continuous: true }}
+      modalTitle="พูดข้อความ"
+      generateButtonText="สร้าง"
+      onGenerate={handleGenerate}
+      onGenerateComplete={(result) => {
+        setResults((prev) => [...prev, result]);
+      }}
+      onGenerateError={(error) => {
+        console.error("Error:", error);
+      }}
+    >
+      <MainContent results={results} />
+    </SpeechProvider>
+  );
+}
+
+// Content Component
+function MainContent({ results }: { results: string[] }) {
+  const { isWidgetEnabled, toggleWidget } = useSpeechContext();
+
+  return (
+    <div style={{ padding: 20 }}>
+      <h1>🎙️ Speech Recognition Demo</h1>
+
+      <button onClick={toggleWidget}>
+        {isWidgetEnabled ? "ปิด" : "เปิด"} Voice Widget
+      </button>
+
+      <h2>Results:</h2>
+      <ul>
+        {results.map((r, i) => (
+          <li key={i}>{r}</li>
+        ))}
+      </ul>
+
+      <p>👈 กดปุ่มไมค์ที่มุมซ้ายล่างเพื่อเริ่มพูด</p>
+    </div>
+  );
+}
+
+export default App;
+```
+
+## 🔧 Utilities
+
+```tsx
+import {
+  isSpeechRecognitionSupported,
+  requestMicrophonePermission,
+  getSupportedLanguages,
+} from "@poovit-banton/speech-recognition-sdk";
+
+// เช็คว่า browser รองรับไหม
+if (isSpeechRecognitionSupported()) {
+  console.log("รองรับ!");
+}
+
+// ขอ permission ไมค์
+const hasPermission = await requestMicrophonePermission();
+
+// ดูภาษาที่รองรับ
+const languages = getSupportedLanguages();
+```
+
+## 📄 License
+
+MIT © Poovit Banton
+
+---
+
+Made with ❤️ by DFM Team