@molecule/app-audio-recorder-react 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,174 @@
+<!--
+AUTO-GENERATED — DO NOT EDIT THIS FILE.
+Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
+Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
+To change this document, edit the module-level JSDoc in src/index.ts.
+Generated: 2026-08-04T01:50:04.657Z
+-->
+
+# @molecule/app-audio-recorder-react
+
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+Mic-permission + MediaRecorder UI primitive — emits a `Blob` once the
+user finishes recording. Pure browser API; no upload, no transcription.
+
+Used by AI-voice-assistant, AI-meeting-notes (manual capture), and
+AI-customer-service-bot. Wire to any backend by handling `onRecorded`.
+
+## Quick Start
+
+```tsx
+import { AudioRecorder } from '@molecule/app-audio-recorder-react'
+
+;<AudioRecorder
+  maxDurationSeconds={300}
+  onRecorded={({ blob, mimeType, durationSeconds }) => {
+    console.log(`Captured ${durationSeconds}s of ${mimeType}`)
+    uploadVoiceNote(blob)
+  }}
+/>
+```
+
+## Type
+
+`feature`
+
+## Installation
+
+```bash
+npm install @molecule/app-audio-recorder-react @molecule/app-i18n @molecule/app-react @molecule/app-ui react
+npm install -D @types/react
+```
+
+## API
+
+### Interfaces
+
+#### `AudioRecorderProps`
+
+Props for {@link AudioRecorder}.
+
+```typescript
+interface AudioRecorderProps {
+  /**
+   * Called once the user stops recording and a Blob is ready. Parents are
+   * responsible for uploading or persisting the blob.
+   */
+  onRecorded: (rec: AudioRecording) => void
+  /**
+   * Called whenever a recording error occurs (permission denied, no
+   * MediaRecorder support, hardware failure). Optional — the component
+   * surfaces a translated error message regardless.
+   */
+  onError?: (err: Error) => void
+  /**
+   * Optional MIME type to request from MediaRecorder. Falls back to the
+   * browser's default if unsupported. Common values: `'audio/webm'`,
+   * `'audio/mp4'`, `'audio/ogg;codecs=opus'`.
+   */
+  mimeType?: string
+  /**
+   * Maximum recording duration (seconds). When reached, recording stops
+   * automatically and `onRecorded` fires. `0` (default) means unlimited.
+   */
+  maxDurationSeconds?: number
+  /** `data-mol-id` attribute for AI-agent selectors. */
+  dataMolId?: string
+  /** Extra classes appended via the ClassMap `cn()` helper. */
+  className?: string
+}
+```
+
+#### `AudioRecording`
+
+Result emitted via `onRecorded` once a recording finishes.
+
+```typescript
+interface AudioRecording {
+  /** The captured audio as a `Blob`. */
+  blob: Blob
+  /** Audio MIME type (e.g. `'audio/webm'`). */
+  mimeType: string
+  /** Recording duration in seconds (whole-second precision). */
+  durationSeconds: number
+}
+```
+
+### Types
+
+#### `AudioRecorderState`
+
+Recorder lifecycle states.
+
+```typescript
+type AudioRecorderState = 'idle' | 'recording' | 'paused' | 'processed' | 'error'
+```
+
+### Functions
+
+#### `AudioRecorder(props)`
+
+Mic-permission + MediaRecorder UI primitive — emits a `Blob` once the user
+finishes recording. Pure browser API; no upload, no transcription. Wire to
+any backend by listening to `onRecorded` and POST-ing the blob.
+
+Renders a status badge, an elapsed-time readout, and three buttons:
+Record (idle/processed) → Pause/Resume + Stop (recording/paused).
+All button labels and status text flow through `t()` with English
+`defaultValue` fallbacks; drop in a companion locale bond to translate.
+
+Styling is delegated to `getClassMap()` — no Tailwind / raw class names.
+
+```typescript
+function AudioRecorder({
+  onRecorded,
+  onError,
+  mimeType,
+  maxDurationSeconds = 0,
+  dataMolId,
+  className,
+}: AudioRecorderProps): ReactElement<unknown, string | JSXElementConstructor<any>>
+```
+
+- `props` — Component props.
+
+**Returns:** The rendered recorder element.
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/app-i18n` ^1.0.1
+- `@molecule/app-react` ^1.0.1
+- `@molecule/app-ui` ^1.0.1
+- `react` ^18.0.0 || ^19.0.0
+
+### Runtime Dependencies
+
+- `@molecule/app-i18n`
+- `@molecule/app-react`
+- `@molecule/app-ui`
+- `react`
+
+`getUserMedia` only exists in a secure context — the recorder works on
+`https://` and `localhost`, and permanently shows the error state on
+plain HTTP. The requested `mimeType` is best-effort: unsupported types
+silently fall back to the browser default (the actual type is reported
+in `onRecorded`). Reaching `maxDurationSeconds` auto-stops and still
+fires `onRecorded`. The recording dot's pulse uses a `mol-pulse` CSS
+animation shipped in the molecule base stylesheet
+(`@molecule/app-ui-tailwind`'s `base.css`, loaded by every molecule app),
+so the dot animates out of the box; a host that does not load that
+stylesheet can define `@keyframes mol-pulse { 50% { opacity: .4 } }`
+itself (without it the dot is static but recording still works).
+Translations come from the companion
+`@molecule/app-locales-audio-recorder` locale bond.
+
+## Translations
+
+Translation strings are provided by `@molecule/app-locales-audio-recorder`.

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@molecule/app-audio-recorder-react",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Mic permission + MediaRecorder wrapper that emits a Blob — voice notes, meeting capture, AI voice agents",
+  "homepage": "https://www.molecule.dev/packages/app-audio-recorder-react",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,7 +18,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "keywords": [
     "molecule",
@@ -27,17 +29,22 @@
     "react"
   ],
   "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/app/features/audio-recorder-react"
+  },
   "peerDependencies": {
-    "@molecule/app-i18n": "^1.0.0",
-    "@molecule/app-react": "^1.0.0",
-    "@molecule/app-ui": "^1.0.0",
+    "@molecule/app-i18n": "^1.0.1",
+    "@molecule/app-react": "^1.0.1",
+    "@molecule/app-ui": "^1.0.1",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@molecule/app-i18n": "1.0.0",
-    "@molecule/app-react": "1.0.0",
-    "@molecule/app-ui": "1.0.0",
-    "@molecule/app-ui-tailwind": "1.0.0",
+    "@molecule/app-i18n": "1.0.2",
+    "@molecule/app-react": "1.5.1",
+    "@molecule/app-ui": "1.1.1",
+    "@molecule/app-ui-tailwind": "1.1.3",
     "@testing-library/dom": "10.4.1",
     "@testing-library/react": "16.3.2",
     "@types/node": "26.1.2",
@@ -47,6 +54,6 @@
     "react": "19.2.8",
     "react-dom": "19.2.8",
     "typescript": "6.0.3",
-    "vitest": "4.1.10"
+    "vitest": "4.1.11"
   }
 }