feat: add useDetectedEntities reactive (as-you-type) hook

CHANGELOG.md

@@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `useDetectedEntities(text, options?)` hook — reactive, debounced detection of a
+  changing string (as-you-type). Returns `{ entities, isDetecting, status, error }`,
+  is cancellation-safe (latest text wins), and manages model readiness internally.
 - `useDataDetector` hook — tracks model readiness (`status`/`isReady`/`error`),
   exposes `detect`, and auto-downloads the model on Android (opt out with
   `autoPrepare: false`).

README.md

@@ -16,7 +16,7 @@ Cross-platform text data detection for React Native. Uses **NSDataDetector** on
 - **Addresses** — Detect street addresses with parsed components (iOS)
 - **Dates** — Detect dates and times with ISO 8601 output
 - **Native accuracy** — Uses battle-tested platform APIs instead of regex
-- **React hook** — [`useDataDetector`](#usedatadetectoroptions) tracks model readiness and auto-downloads on Android
+- **React hooks** — `useDataDetector` (imperative) and `useDetectedEntities` (reactive, as-you-type); both track model readiness and auto-download on Android
 - **Multiple languages** — Choose from 15 ML Kit language models on Android
 - **Expo Modules API** — Built with the modern Expo native module system
 
@@ -65,10 +65,17 @@ const phones = await detect('Call 555-1234 or visit https://example.com', {
 const fr = await detect('Appelez-moi au 01 23 45 67 89', { language: 'fr' });
 ```
 
-### Hook
+### Hooks
 
-The `useDataDetector` hook tracks model readiness and, on Android, downloads the
-model automatically on mount. On iOS the model is always ready.
+There are two hooks for two situations:
+
+- **`useDataDetector`** — *imperative*. Tracks model readiness and hands you a
+  `detect` function you call yourself (e.g. once per chat message).
+- **`useDetectedEntities`** — *reactive*. Pass it a (changing) string and it returns
+  the detected entities, debounced and recomputed as the text changes — ideal for
+  as-you-type input.
+
+Both download the model automatically on Android and are no-ops on iOS (always ready).
 
 ```tsx
 import { useDataDetector } from 'react-native-data-detector';
@@ -87,6 +94,22 @@ function MyComponent() {
 }
 ```
 
+```tsx
+import { useDetectedEntities } from 'react-native-data-detector';
+
+function LiveInput() {
+  const [text, setText] = useState('');
+  const { entities, isDetecting } = useDetectedEntities(text, { debounceMs: 250 });
+
+  return (
+    <>
+      <TextInput value={text} onChangeText={setText} />
+      <Text>{entities.length} detected{isDetecting ? '…' : ''}</Text>
+    </>
+  );
+}
+```
+
 ## API
 
 ### `prepareModel(options?)`
@@ -145,6 +168,30 @@ React hook that tracks model availability and, on Android, downloads the languag
 | `isReady` | `boolean` | `true` when `status === 'ready'`. |
 | `error` | `Error \| null` | The last preparation error, or `null`. |
 
+### `useDetectedEntities(text, options?)`
+
+Reactive hook: pass a (changing) string and get back the detected entities, recomputed as the text changes. Debounced and cancellation-safe (the latest text wins), so it suits as-you-type input. Manages model readiness internally.
+
+**Parameters:**
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `text` | `string` | — | The text to detect entities in. |
+| `options.debounceMs` | `number` | `300` | Debounce applied to `text` before detecting. |
+| `options.types` | `DetectionType[]` | All types | Which entity types to detect. |
+| `options.language` | `ModelLanguage` | `'en'` | Which language model to use (Android only). |
+| `options.enabled` | `boolean` | `true` | When `false`, detection pauses and the last result is kept. |
+| `options.autoPrepare` | `boolean` | `true` | Download the model on mount if needed (Android). |
+
+**Returns:** `UseDetectedEntitiesResult`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `entities` | `DetectedEntity[]` | Entities detected in the debounced `text`. |
+| `isDetecting` | `boolean` | `true` while a detection for the latest text is in flight. |
+| `status` | `ModelStatus` | Current model download state. |
+| `error` | `Error \| null` | The last detection or model error, or `null`. |
+
 ### `downloadModel()`
 
 > **Deprecated since 0.3.0** — use [`prepareModel()`](#preparemodeloptions) instead. Kept as an alias (always targets the default `'en'` model) and will be removed in a future major version.