@portabletext/plugin-typeahead-picker 1.0.0 → 2.0.1

package/README.md

@@ -7,6 +7,7 @@
 The `useTypeaheadPicker` hook provides the state and logic needed to build typeahead pickers (emoji pickers, mention pickers, slash commands, etc.) for the Portable Text Editor. It manages keyword matching, keyboard navigation, and triggering of actions, but is not concerned with the UI, how the picker is rendered, or how it's positioned in the document.
 
 ```tsx
+import {EditorProvider, PortableTextEditable} from '@portabletext/editor'
 import {raise} from '@portabletext/editor/behaviors'
 import {
   defineTypeaheadPicker,
@@ -14,7 +15,7 @@ import {
   type AutoCompleteMatch,
 } from '@portabletext/plugin-typeahead-picker'
 
-// With `autoCompleteWith` configured, matches must include `type: 'exact' | 'partial'`
+// With `delimiter` configured, matches must include `type: 'exact' | 'partial'`
 // for auto-completion to work. Use `AutoCompleteMatch` as the base type.
 type EmojiMatch = AutoCompleteMatch & {
   key: string
@@ -23,13 +24,15 @@ type EmojiMatch = AutoCompleteMatch & {
 }
 
 const emojiPicker = defineTypeaheadPicker<EmojiMatch>({
-  // Pattern to match trigger + keyword. The capture group (\S*) becomes the keyword.
-  // This matches `:` followed by any non-whitespace characters.
-  pattern: /:(\S*)/,
+  // Trigger pattern - activates the picker when typed
+  trigger: /:/,
 
-  // Optional autoCompleteWith enables auto-completion.
+  // Keyword pattern - matches characters after the trigger
+  keyword: /\S*/,
+
+  // Optional delimiter enables auto-completion.
   // Typing `:joy:` will auto-insert if "joy" is an exact match.
-  autoCompleteWith: ':',
+  delimiter: ':',
 
   // Return matches for the keyword. Can be sync or async (with mode: 'async').
   getMatches: ({keyword}) => searchEmojis(keyword),
@@ -44,7 +47,7 @@ const emojiPicker = defineTypeaheadPicker<EmojiMatch>({
   ],
 })
 
-function EmojiPicker() {
+function EmojiPickerPlugin() {
   // Activate the picker and get its current state
   const picker = useTypeaheadPicker(emojiPicker)
 
@@ -76,18 +79,30 @@ function EmojiPicker() {
     </ul>
   )
 }
+
+// Render the picker inside EditorProvider, alongside PortableTextEditable
+function MyEditor() {
+  return (
+    <EditorProvider /* ...config */>
+      <PortableTextEditable />
+      <EmojiPickerPlugin />
+    </EditorProvider>
+  )
+}
 ```
 
+The picker component must be rendered inside `EditorProvider` to access the editor context. Position it as a sibling to `PortableTextEditable` - you'll handle the visual positioning (popover, dropdown, etc.) separately with CSS or a positioning library.
+
 ## How It Works
 
-The picker activates when users type text matching the `pattern` (e.g., `:smile` or `@john`).
+The picker activates when users type the `trigger` pattern (e.g., `:` or `@`). The `keyword` pattern then matches characters typed after the trigger.
 
 - **Keyboard shortcuts are built-in**:
   - `Enter` or `Tab` inserts the selected match
   - `↑` / `↓` navigate through matches
   - `Esc` dismisses the picker
 - **Mouse interactions are opt-in**: Use `send({type: 'navigate to', index})` and `send({type: 'select'})` to enable hover and click
-- **Auto-completion**: With `autoCompleteWith` configured, typing the delimiter after an exact match auto-inserts it (e.g., `:joy:` auto-inserts the emoji)
+- **Auto-completion**: With `delimiter` configured, typing the delimiter after an exact match auto-inserts it (e.g., `:joy:` auto-inserts the emoji)
 
 ## Examples
 
@@ -95,8 +110,9 @@ The picker activates when users type text matching the `pattern` (e.g., `:smile`
 
 ```ts
 const emojiPicker = defineTypeaheadPicker<EmojiMatch>({
-  pattern: /:(\S*)/,
-  autoCompleteWith: ':',
+  trigger: /:/,
+  keyword: /\S*/,
+  delimiter: ':',
   getMatches: ({keyword}) => searchEmojis(keyword),
   actions: [
     ({event}) => [
@@ -112,11 +128,12 @@ const emojiPicker = defineTypeaheadPicker<EmojiMatch>({
 ### Mention picker (async with debounce)
 
 ```ts
-// Without `autoCompleteWith`, the `type` field is not required on matches.
+// Without `delimiter`, the `type` field is not required on matches.
 // MentionMatch can just be: { id: string; name: string }
 const mentionPicker = defineTypeaheadPicker<MentionMatch>({
   mode: 'async',
-  pattern: /@(\w*)/,
+  trigger: /@/,
+  keyword: /\w*/,
   debounceMs: 200,
   getMatches: async ({keyword}) => api.searchUsers(keyword),
   actions: [
@@ -136,9 +153,10 @@ const mentionPicker = defineTypeaheadPicker<MentionMatch>({
 ### Slash command picker (start of block only)
 
 ```ts
-// Without `autoCompleteWith`, the `type` field is not required on matches.
+// Without `delimiter`, the `type` field is not required on matches.
 const commandPicker = defineTypeaheadPicker<CommandMatch>({
-  pattern: /^\/(\w*)/, // ^ anchors to start of block
+  trigger: /^\//, // ^ anchors to start of block
+  keyword: /\w*/,
   getMatches: ({keyword}) => searchCommands(keyword),
   actions: [
     ({event}) => {
@@ -173,73 +191,51 @@ Creates a picker definition to pass to `useTypeaheadPicker`.
 
 **Config:**
 
-| Property           | Type                                   | Description                                                                                                                                                                    |
-| ------------------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `pattern`          | `RegExp`                               | Pattern for matching trigger + keyword. Use a capture group for the keyword (e.g., `/:(\S*)/`, `/@(\w*)/`). Can include position anchors like `^` for start-of-block triggers. |
-| `autoCompleteWith` | `string?`                              | Optional delimiter that triggers auto-completion (e.g., `:` for `:joy:`)                                                                                                       |
-| `mode`             | `'sync' \| 'async'`                    | Whether `getMatches` returns synchronously or a Promise (default: `'sync'`)                                                                                                    |
-| `debounceMs`       | `number?`                              | Delay in ms before calling `getMatches`. Useful for both async (API calls) and sync (expensive local search) modes. (default: `0`)                                             |
-| `getMatches`       | `(ctx: {keyword: string}) => TMatch[]` | Function that returns matches for the keyword                                                                                                                                  |
-| `actions`          | `Array<TypeaheadSelectActionSet>`      | Actions to execute when a match is selected                                                                                                                                    |
+| Property     | Type                                   | Description                                                                                                                             |
+| ------------ | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `trigger`    | `RegExp`                               | Pattern that activates the picker. Can include `^` for start-of-block triggers. Must be single-character (e.g., `/:/`, `/@/`, `/^\//`). |
+| `keyword`    | `RegExp`                               | Pattern matching characters after the trigger (e.g., `/\S*/`, `/\w*/`).                                                                 |
+| `delimiter`  | `string?`                              | Optional delimiter that triggers auto-completion (e.g., `':'` for `:joy:`)                                                              |
+| `mode`       | `'sync' \| 'async'`                    | Whether `getMatches` returns synchronously or a Promise (default: `'sync'`)                                                             |
+| `debounceMs` | `number?`                              | Delay in ms before calling `getMatches`. Useful for both async (API calls) and sync (expensive local search) modes. (default: `0`)      |
+| `getMatches` | `(ctx: {keyword: string}) => TMatch[]` | Function that returns matches for the keyword                                                                                           |
+| `actions`    | `Array<TypeaheadSelectActionSet>`      | Actions to execute when a match is selected                                                                                             |
 
-**Pattern rules:**
+**Trigger pattern rules:**
 
-- If pattern has capture groups: keyword = first capture group
-- If no capture group: keyword = entire match
+- Must be a single-character trigger (e.g., `:`, `@`, `/`)
+- Multi-character triggers (e.g., `##`) are not supported
 - Position anchors (`^`) allow start-of-block constraints
-- Regex flags are ignored (the picker normalizes patterns internally)
 
 **How triggering works:**
 
-The picker activates the moment a trigger character is typed - not later when more text matches. This is the key to understanding pattern requirements:
+The picker activates the moment a trigger character is typed. After activation, the keyword is tracked via editor selection changes.
 
 ```
-User types `:` → Pattern /:(\S*)/ matches → Picker activates with keyword ""
+User types `:` → Trigger matches → Picker activates with keyword ""
 User types `j` → Keyword updates to "j" (via selection tracking)
 User types `o` → Keyword updates to "jo"
 User types `y` → Keyword updates to "joy"
 ```
 
-The pattern must match **immediately when the trigger is typed**. After activation, the keyword is tracked via editor selection changes, not by re-running the pattern.
-
-**Why some patterns don't work:**
-
-Multi-character triggers like `##` fail because the picker can only activate on the character you just typed:
-
-```
-User types `#` → Pattern /##(\w*)/ doesn't match yet → Nothing happens
-User types `#` → Pattern matches "##", but the first # was already there
-                 Picker only activates on newly typed triggers, not existing text
-```
-
-Same issue with patterns requiring specific characters mid-keyword like `/:(\w*)-(\w*)/`:
-
-```
-User types `:foo` → Pattern doesn't match yet (needs a `-`)
-User types `-`    → Pattern matches `:foo-`, but `:foo` was already there
-                    Picker only activates on newly typed triggers
-```
-
-**Pattern compatibility summary:**
+**Trigger compatibility summary:**
 
-| Pattern          | Example input | Works? | Why                               |
-| ---------------- | ------------- | ------ | --------------------------------- |
-| `/:(\S*)/`       | `:joy`        | ✅     | `:` alone triggers, keyword grows |
-| `/@(\w*)/`       | `@john`       | ✅     | `@` alone triggers, keyword grows |
-| `/^\/(\w*)/`     | `/cmd`        | ✅     | `/` at block start triggers       |
-| `/##(\w*)/`      | `##tag`       | ❌     | `#` alone doesn't match pattern   |
-| `/:(\w*)-(\w*)/` | `:a-b`        | ❌     | `:` alone doesn't match pattern   |
+| Trigger | Example input | Works? | Why                              |
+| ------- | ------------- | ------ | -------------------------------- |
+| `/:/`   | `:joy`        | ✅     | Single-char trigger              |
+| `/@/`   | `@john`       | ✅     | Single-char trigger              |
+| `/^\//` | `/cmd`        | ✅     | Single-char with position anchor |
+| `/##/`  | `##tag`       | ❌     | Multi-char triggers unsupported  |
 
-**autoCompleteWith requirements:**
+**delimiter requirements:**
 
-When using `autoCompleteWith`, the delimiter character must be included in the keyword's character class, otherwise typing it dismisses the picker:
+Single-character delimiters work regardless of whether the character is included in the keyword pattern. Multi-character delimiters are not supported.
 
-| Pattern    | autoCompleteWith | Example  | Works? | Why                                                 |
-| ---------- | ---------------- | -------- | ------ | --------------------------------------------------- |
-| `/:(\S*)/` | `:`              | `:joy:`  | ✅     | `\S` matches `:`, cursor stays in match             |
-| `/:(\w*)/` | `:`              | `:joy:`  | ✅     | Cursor at match boundary, still valid               |
-| `/#(\w*)/` | `#`              | `#tag#`  | ✅     | Cursor at match boundary, still valid               |
-| `/#(\w*)/` | `##`             | `#tag##` | ❌     | First `#` moves cursor past match, picker dismisses |
+| keyword | delimiter | Example  | Works? | Why                                     |
+| ------- | --------- | -------- | ------ | --------------------------------------- |
+| `/\S*/` | `:`       | `:joy:`  | ✅     | `\S` matches `:`, keyword becomes `joy` |
+| `/\w*/` | `:`       | `:joy:`  | ✅     | `\w` stops at `:`, keyword is `joy`     |
+| `/\w*/` | `##`      | `#tag##` | ❌     | Multi-char delimiter not supported      |
 
 ### `useTypeaheadPicker(definition)`
 
@@ -250,7 +246,7 @@ React hook that activates a picker and returns its state.
 | Property                         | Description                                                                                                  |
 | -------------------------------- | ------------------------------------------------------------------------------------------------------------ |
 | `snapshot.matches(state)`        | Check picker state: `'idle'`, `{active: 'loading'}`, `{active: 'no matches'}`, `{active: 'showing matches'}` |
-| `snapshot.context.keyword`       | The current keyword (extracted from capture group)                                                           |
+| `snapshot.context.keyword`       | The current keyword                                                                                          |
 | `snapshot.context.matches`       | Array of matches from `getMatches`                                                                           |
 | `snapshot.context.selectedIndex` | Index of the currently selected match                                                                        |
 | `send(event)`                    | Dispatch events: `{type: 'select'}`, `{type: 'dismiss'}`, `{type: 'navigate to', index}`                     |
@@ -301,7 +297,7 @@ When users type quickly, earlier slow requests may complete after later fast req
 If `getMatches` throws or rejects, the error is captured in `snapshot.context.error`. The picker transitions to `'no matches'` state and continues to function.
 
 ```tsx
-function EmojiPicker() {
+function EmojiPickerPlugin() {
   const picker = useTypeaheadPicker(emojiPicker)
   const {error} = picker.snapshot.context
 
@@ -326,7 +322,8 @@ Action functions receive more than just the event. The full payload includes acc
 
 ```tsx
 const commandPicker = defineTypeaheadPicker<CommandMatch>({
-  pattern: /^\/(\w*)/,
+  trigger: /^\//,
+  keyword: /\w*/,
   getMatches: ({keyword}) => searchCommands(keyword),
   actions: [
     ({event, snapshot}) => {
@@ -388,7 +385,8 @@ Choose debounce values based on your data source:
 ```tsx
 // Local data - no debounce needed
 const emojiPicker = defineTypeaheadPicker({
-  pattern: /:(\S*)/,
+  trigger: /:/,
+  keyword: /\S*/,
   getMatches: ({keyword}) => filterEmojis(keyword), // Fast local filter
   // ...
 })
@@ -397,7 +395,8 @@ const emojiPicker = defineTypeaheadPicker({
 const mentionPicker = defineTypeaheadPicker({
   mode: 'async',
   debounceMs: 200,
-  pattern: /@(\w*)/,
+  trigger: /@/,
+  keyword: /\w*/,
   getMatches: async ({keyword}) => api.searchUsers(keyword),
   // ...
 })
@@ -460,17 +459,17 @@ The following keyboard shortcuts are handled automatically by the picker:
 
 ### Picker doesn't activate
 
-- **Check pattern**: Ensure your regex has a capture group for the keyword: `/:(\S*)/` not `/:\S*/`
-- **Check position anchors**: `^` means start of block, not start of line. `hello /command` won't match `/^\/(\w*)/`
+- **Check trigger**: Must be a single-character trigger (e.g., `/:/`, `/@/`)
+- **Check position anchors**: `^` means start of block, not start of line. `hello /command` won't match `/^\//`
 - **Check for conflicts**: Only one picker can be active at a time
-- **Avoid multi-character triggers**: Patterns like `/##(\w*)/` don't work because the picker only activates on newly typed triggers, not existing text
+- **Avoid multi-character triggers**: Triggers like `/##/` don't work because the picker only activates on newly typed single characters
 
 ### Auto-completion doesn't work
 
-- **Check `autoCompleteWith`**: Must be set (e.g., `autoCompleteWith: ':'`)
+- **Check `delimiter`**: Must be set (e.g., `delimiter: ':'`)
 - **Check match type**: Matches must include `type: 'exact' | 'partial'`
 - **Check for exact match**: Auto-completion only triggers when exactly one match has `type: 'exact'`
-- **Check character class**: The keyword character class must match the `autoCompleteWith` character. Use `\S*` (matches any non-whitespace including `:`) rather than `\w*` (only matches word characters) when `autoCompleteWith: ':'`
+- **Check keyword pattern**: The keyword pattern must allow the delimiter character at the boundary. Use `\S*` (matches any non-whitespace) when `delimiter: ':'`
 
 ### Stale matches appear
 

package/dist/index.d.ts

@@ -1,34 +1,58 @@
 import type {EditorSelection} from '@portabletext/editor'
 import type {BehaviorActionSet} from '@portabletext/editor/behaviors'
 
-declare type AsyncConfigWithAutoComplete<TMatch extends AutoCompleteMatch> =
-  BaseConfigWithAutoComplete<TMatch> & {
+declare type AsyncConfigWithDelimiter<TMatch extends AutoCompleteMatch> =
+  BaseConfigWithDelimiter<TMatch> & {
+    /**
+     * Set to `'async'` when `getMatches` returns a Promise.
+     */
     mode: 'async'
+    /**
+     * Debounce delay in milliseconds before calling `getMatches`.
+     * Recommended for API calls to reduce request frequency.
+     * @defaultValue `0` (no debounce)
+     */
     debounceMs?: number
-    getMatches: (context: {keyword: string}) => Promise<Array<TMatch>>
+    /**
+     * Async function that returns matches for the current keyword.
+     * Called whenever the keyword changes (after debounce if configured).
+     */
+    getMatches: (context: {keyword: string}) => Promise<ReadonlyArray<TMatch>>
   }
 
-declare type AsyncConfigWithoutAutoComplete<TMatch extends object> =
-  BaseConfigWithoutAutoComplete<TMatch> & {
+declare type AsyncConfigWithoutDelimiter<TMatch extends object> =
+  BaseConfigWithoutDelimiter<TMatch> & {
+    /**
+     * Set to `'async'` when `getMatches` returns a Promise.
+     */
     mode: 'async'
+    /**
+     * Debounce delay in milliseconds before calling `getMatches`.
+     * Recommended for API calls to reduce request frequency.
+     * @defaultValue `0` (no debounce)
+     */
     debounceMs?: number
-    getMatches: (context: {keyword: string}) => Promise<Array<TMatch>>
+    /**
+     * Async function that returns matches for the current keyword.
+     * Called whenever the keyword changes (after debounce if configured).
+     */
+    getMatches: (context: {keyword: string}) => Promise<ReadonlyArray<TMatch>>
   }
 
 /**
  * Match type for pickers with auto-completion support.
- * Use this when `autoCompleteWith` is configured.
+ * Use this when `delimiter` is configured.
  *
  * The `type` property indicates how well the match corresponds to the keyword:
  * - `'exact'` - The keyword matches this item exactly (e.g., keyword `joy` matches emoji `:joy:`)
  * - `'partial'` - The keyword partially matches this item (e.g., keyword `jo` matches `:joy:`)
  *
- * When `autoCompleteWith` is configured and there's exactly one `'exact'` match,
+ * When `delimiter` is configured and there's exactly one `'exact'` match,
  * the picker will auto-insert that match.
  *
  * @example
  * ```ts
- * // With autoCompleteWith - type field required for auto-completion
+ * // With delimiter - type field required for auto-completion
  * type EmojiMatch = AutoCompleteMatch & {
  *   key: string
  *   emoji: string
@@ -42,15 +66,57 @@ export declare type AutoCompleteMatch = {
   type: 'exact' | 'partial'
 }
 
-declare type BaseConfigWithAutoComplete<TMatch extends AutoCompleteMatch> = {
-  pattern: RegExp
-  autoCompleteWith: string
+declare type BaseConfigWithDelimiter<TMatch extends AutoCompleteMatch> = {
+  /**
+   * Pattern that activates the picker. Must be a single character.
+   * Can include `^` for start-of-block triggers.
+   *
+   * @example `/:/` - activates on colon
+   * @example `/@/` - activates on at-sign
+   * @example `/^\//` - activates on slash at start of block
+   */
+  trigger: RegExp
+  /**
+   * Pattern matching the keyword portion after the trigger.
+   * The entire match becomes the keyword passed to `getMatches`.
+   * Common patterns: non-whitespace (`\S*`) or word characters (`\w*`).
+   */
+  keyword: RegExp
+  /**
+   * Character that triggers auto-completion.
+   * Typing this after a keyword with an exact match auto-inserts it.
+   *
+   * @example `':'` - typing `:joy:` auto-inserts the joy emoji
+   */
+  delimiter: string
+  /**
+   * Actions to execute when a match is selected.
+   * Typically deletes the trigger text and inserts the selected content.
+   */
   actions: Array<TypeaheadSelectActionSet<TMatch>>
 }
 
-declare type BaseConfigWithoutAutoComplete<TMatch extends object> = {
-  pattern: RegExp
-  autoCompleteWith?: undefined
+declare type BaseConfigWithoutDelimiter<TMatch extends object> = {
+  /**
+   * Pattern that activates the picker. Must be a single character.
+   * Can include `^` for start-of-block triggers.
+   *
+   * @example `/:/` - activates on colon
+   * @example `/@/` - activates on at-sign
+   * @example `/^\//` - activates on slash at start of block
+   */
+  trigger: RegExp
+  /**
+   * Pattern matching the keyword portion after the trigger.
+   * The entire match becomes the keyword passed to `getMatches`.
+   * Common patterns: non-whitespace (`\S*`) or word characters (`\w*`).
+   */
+  keyword: RegExp
+  delimiter?: undefined
+  /**
+   * Actions to execute when a match is selected.
+   * Typically deletes the trigger text and inserts the selected content.
+   */
   actions: Array<TypeaheadSelectActionSet<TMatch>>
 }
 
@@ -60,13 +126,11 @@ declare type BaseConfigWithoutAutoComplete<TMatch extends object> = {
  * @example Emoji picker with auto-complete
  * ```ts
  * const emojiPicker = defineTypeaheadPicker({
- *   pattern: /:(\S*)/,
- *   autoCompleteWith: ':',
+ *   trigger: /:/,
+ *   keyword: /[\S]+/,
+ *   delimiter: ':',
  *   getMatches: ({keyword}) => searchEmojis(keyword),
- *   actions: [({event}) => [
- *     raise({type: 'delete', at: event.patternSelection}),
- *     raise({type: 'insert.text', text: event.match.emoji}),
- *   ]],
+ *   actions: [insertEmojiAction],
  * })
  * ```
  *
@@ -74,47 +138,43 @@ declare type BaseConfigWithoutAutoComplete<TMatch extends object> = {
  * ```ts
  * const mentionPicker = defineTypeaheadPicker({
  *   mode: 'async',
- *   pattern: /@(\w*)/,
+ *   trigger: /@/,
+ *   keyword: /[\w]+/,
  *   debounceMs: 200,
  *   getMatches: async ({keyword}) => api.searchUsers(keyword),
- *   actions: [({event}) => [
- *     raise({type: 'delete', at: event.patternSelection}),
- *     raise({type: 'insert.text', text: event.match.name}),
- *   ]],
+ *   actions: [insertMentionAction],
  * })
  * ```
  *
  * @example Slash commands at start of block
  * ```ts
  * const slashCommandPicker = defineTypeaheadPicker({
- *   pattern: /^\/(\w*)/,  // ^ anchors to start of block
+ *   trigger: /^\//,
+ *   keyword: /[\w]+/,
  *   getMatches: ({keyword}) => filterCommands(keyword),
- *   actions: [({event}) => [
- *     raise({type: 'delete', at: event.patternSelection}),
- *     raise(event.match.action),
- *   ]],
+ *   actions: [executeCommandAction],
  * })
  * ```
  *
  * @public
  */
 export declare function defineTypeaheadPicker<TMatch extends object>(
-  config: SyncConfigWithoutAutoComplete<TMatch>,
+  config: SyncConfigWithoutDelimiter<TMatch>,
 ): TypeaheadPickerDefinition<TMatch>
 
 /** @public */
 export declare function defineTypeaheadPicker<TMatch extends AutoCompleteMatch>(
-  config: SyncConfigWithAutoComplete<TMatch>,
+  config: SyncConfigWithDelimiter<TMatch>,
 ): TypeaheadPickerDefinition<TMatch>
 
 /** @public */
 export declare function defineTypeaheadPicker<TMatch extends object>(
-  config: AsyncConfigWithoutAutoComplete<TMatch>,
+  config: AsyncConfigWithoutDelimiter<TMatch>,
 ): TypeaheadPickerDefinition<TMatch>
 
 /** @public */
 export declare function defineTypeaheadPicker<TMatch extends AutoCompleteMatch>(
-  config: AsyncConfigWithAutoComplete<TMatch>,
+  config: AsyncConfigWithDelimiter<TMatch>,
 ): TypeaheadPickerDefinition<TMatch>
 
 /**
@@ -142,20 +202,46 @@ export declare function defineTypeaheadPicker<TMatch extends AutoCompleteMatch>(
  */
 export declare type GetMatches<TMatch extends object> = (context: {
   keyword: string
-}) => Array<TMatch> | Promise<Array<TMatch>>
+}) => ReadonlyArray<TMatch> | Promise<ReadonlyArray<TMatch>>
 
-declare type SyncConfigWithAutoComplete<TMatch extends AutoCompleteMatch> =
-  BaseConfigWithAutoComplete<TMatch> & {
+declare type SyncConfigWithDelimiter<TMatch extends AutoCompleteMatch> =
+  BaseConfigWithDelimiter<TMatch> & {
+    /**
+     * Whether `getMatches` returns synchronously or asynchronously.
+     * @defaultValue `'sync'`
+     */
     mode?: 'sync'
+    /**
+     * Debounce delay in milliseconds before calling `getMatches`.
+     * Useful for expensive local searches.
+     * @defaultValue `0` (no debounce)
+     */
     debounceMs?: number
-    getMatches: (context: {keyword: string}) => Array<TMatch>
+    /**
+     * Function that returns matches for the current keyword.
+     * Called whenever the keyword changes (after debounce if configured).
+     */
+    getMatches: (context: {keyword: string}) => ReadonlyArray<TMatch>
   }
 
-declare type SyncConfigWithoutAutoComplete<TMatch extends object> =
-  BaseConfigWithoutAutoComplete<TMatch> & {
+declare type SyncConfigWithoutDelimiter<TMatch extends object> =
+  BaseConfigWithoutDelimiter<TMatch> & {
+    /**
+     * Whether `getMatches` returns synchronously or asynchronously.
+     * @defaultValue `'sync'`
+     */
     mode?: 'sync'
+    /**
+     * Debounce delay in milliseconds before calling `getMatches`.
+     * Useful for expensive local searches.
+     * @defaultValue `0` (no debounce)
+     */
     debounceMs?: number
-    getMatches: (context: {keyword: string}) => Array<TMatch>
+    /**
+     * Function that returns matches for the current keyword.
+     * Called whenever the keyword changes (after debounce if configured).
+     */
+    getMatches: (context: {keyword: string}) => ReadonlyArray<TMatch>
   }
 
 /**
@@ -224,7 +310,7 @@ export declare type TypeaheadPickerContext<TMatch> = {
   /** The extracted keyword from the trigger pattern (e.g., `joy` from `:joy`) */
   keyword: string
   /** The current list of matches returned by `getMatches` */
-  matches: Array<TMatch>
+  matches: ReadonlyArray<TMatch>
   /** Index of the currently selected match (for keyboard navigation and highlighting) */
   selectedIndex: number
   /** Error from `getMatches` if it threw, otherwise `undefined` */
@@ -239,8 +325,9 @@ export declare type TypeaheadPickerContext<TMatch> = {
  * @example
  * ```ts
  * const emojiPicker = defineTypeaheadPicker({
- *   pattern: /:(\S*)/,
- *   autoCompleteWith: ':',
+ *   trigger: /:/,
+ *   keyword: /[\S]+/,
+ *   delimiter: ':',
  *   getMatches: ({keyword}) => searchEmojis(keyword),
  *   actions: [insertEmojiAction],
  * })
@@ -273,32 +360,29 @@ export declare type TypeaheadPickerDefinition<TMatch extends object = object> =
 
 declare type TypeaheadPickerDefinitionBase<TMatch extends object> = {
   /**
-   * RegExp pattern for matching trigger + keyword.
-   *
-   * If pattern has capture groups: keyword = first capture group (additional groups ignored).
-   * If no capture group: keyword = entire match.
-   *
-   * Can include position anchors like `^` for start-of-block triggers.
+   * Pattern that activates the picker.
+   * Can include positional anchors like `^` for start-of-block triggers.
    *
-   * @example
-   * ```ts
-   * // Emoji picker - `:` trigger anywhere
-   * pattern: /:(\S*)/
-   *
-   * // Slash commands - `/` only at start of block
-   * pattern: /^\/(\w*)/
+   * @example `/:/` for emoji
+   * @example `/@/` for mentions
+   * @example `/^\//` for slash commands (start of block only)
+   */
+  trigger: RegExp
+  /**
+   * Pattern matching the keyword portion (after trigger, before delimiter).
+   * The entire match is used as the keyword.
    *
-   * // Mentions - `@` trigger anywhere
-   * pattern: /@(\w*)/
-   * ```
+   * @example `/[\S]+/` for emoji (any non-whitespace)
+   * @example `/[\w]+/` for mentions (word characters only)
    */
-  pattern: RegExp
+  keyword: RegExp
   /**
-   * Optional delimiter that triggers auto-completion.
-   * When typed after a keyword with exactly one exact match, that match auto-inserts.
+   * Character that triggers auto-completion.
+   * Typing this after a keyword with exactly one exact match auto-inserts it.
+   *
    * @example `':'` - typing `:joy:` auto-inserts the joy emoji
    */
-  autoCompleteWith?: string
+  delimiter?: string
   /**
    * Actions to execute when a match is selected.
    * Typically deletes the trigger text and inserts the selected content.