@portabletext/plugin-typeahead-picker 6.0.44 → 6.0.46

package/dist/index.d.ts

@@ -1,45 +1,5 @@
-import type {BehaviorActionSet} from '@portabletext/editor/behaviors'
-import type {BehaviorGuard} from '@portabletext/editor/behaviors'
-import type {EditorSelection} from '@portabletext/editor'
-
-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
-    /**
-     * 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 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
-    /**
-     * 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>>
-  }
-
+import { EditorSelection } from "@portabletext/editor";
+import { BehaviorActionSet, BehaviorGuard } from "@portabletext/editor/behaviors";
 /**
  * Match type for pickers with auto-completion support.
  * Use this when `delimiter` is configured.
@@ -63,160 +23,9 @@ declare type AsyncConfigWithoutDelimiter<TMatch extends object> =
  *
  * @public
  */
-export declare type AutoCompleteMatch = {
-  type: 'exact' | 'partial'
-}
-
-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
-  /**
-   * Guard function that runs at trigger time to conditionally prevent activation.
-   * Return `false` to block activation, or `true` to allow it.
-   */
-  guard?: TypeaheadTriggerGuard
-  /**
-   * Called when a match is selected.
-   * Returns behavior actions to execute (e.g., delete trigger text, insert content).
-   */
-  onSelect: TypeaheadSelectActionSet<TMatch>[]
-  /**
-   * Called when the picker is dismissed.
-   * Returns behavior actions to execute (optional cleanup).
-   */
-  onDismiss?: TypeaheadDismissActionSet[]
-}
-
-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
-  /**
-   * Guard function that runs at trigger time to conditionally prevent activation.
-   * Return `false` to block activation, or `true` to allow it.
-   */
-  guard?: TypeaheadTriggerGuard
-  /**
-   * Called when a match is selected.
-   * Returns behavior actions to execute (e.g., delete trigger text, insert content).
-   */
-  onSelect: TypeaheadSelectActionSet<TMatch>[]
-  /**
-   * Called when the picker is dismissed.
-   * Returns behavior actions to execute (optional cleanup).
-   */
-  onDismiss?: TypeaheadDismissActionSet[]
-}
-
-/**
- * Creates a typeahead picker definition to use with {@link useTypeaheadPicker}.
- *
- * @example Emoji picker with auto-complete
- * ```ts
- * const emojiPicker = defineTypeaheadPicker({
- *   trigger: /:/,
- *   keyword: /[\S]+/,
- *   delimiter: ':',
- *   getMatches: ({keyword}) => searchEmojis(keyword),
- *   onSelect: [
- *     ({event}) => [
- *       raise({type: 'delete', at: event.patternSelection}),
- *       raise({type: 'insert.text', text: event.match.emoji}),
- *     ],
- *   ],
- * })
- * ```
- *
- * @example Async mention picker
- * ```ts
- * const mentionPicker = defineTypeaheadPicker({
- *   mode: 'async',
- *   trigger: /@/,
- *   keyword: /[\w]+/,
- *   debounceMs: 200,
- *   getMatches: async ({keyword}) => api.searchUsers(keyword),
- *   onSelect: [
- *     ({event}) => [
- *       raise({type: 'delete', at: event.patternSelection}),
- *       raise({type: 'insert.inline object', inlineObject: {_type: 'mention', userId: event.match.id}}),
- *     ],
- *   ],
- * })
- * ```
- *
- * @example Picker with guard (runs at trigger time)
- * ```ts
- * const emojiPicker = defineTypeaheadPicker({
- *   trigger: /:/,
- *   keyword: /[\S]+/,
- *   getMatches: ({keyword}) => searchEmojis(keyword),
- *   guard: ({snapshot, event, dom}) => {
- *     if (anotherPickerIsOpen()) return false
- *     return true
- *   },
- *   onSelect: [
- *     ({event}) => [
- *       raise({type: 'delete', at: event.patternSelection}),
- *       raise({type: 'insert.text', text: event.match.emoji}),
- *     ],
- *   ],
- * })
- * ```
- *
- * @public
- */
-export declare function defineTypeaheadPicker<TMatch extends object>(
-  config: SyncConfigWithoutDelimiter<TMatch>,
-): TypeaheadPickerDefinition<TMatch>
-
-/** @public */
-export declare function defineTypeaheadPicker<TMatch extends AutoCompleteMatch>(
-  config: SyncConfigWithDelimiter<TMatch>,
-): TypeaheadPickerDefinition<TMatch>
-
-/** @public */
-export declare function defineTypeaheadPicker<TMatch extends object>(
-  config: AsyncConfigWithoutDelimiter<TMatch>,
-): TypeaheadPickerDefinition<TMatch>
-
-/** @public */
-export declare function defineTypeaheadPicker<TMatch extends AutoCompleteMatch>(
-  config: AsyncConfigWithDelimiter<TMatch>,
-): TypeaheadPickerDefinition<TMatch>
-
+type AutoCompleteMatch = {
+  type: 'exact' | 'partial';
+};
 /**
  * Function that retrieves matches for a given keyword.
  *
@@ -240,192 +49,76 @@ export declare function defineTypeaheadPicker<TMatch extends AutoCompleteMatch>(
  *
  * @public
  */
-export declare type GetMatches<TMatch extends object> = (context: {
-  keyword: string
-}) => ReadonlyArray<TMatch> | Promise<ReadonlyArray<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
-    /**
-     * 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 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
-    /**
-     * Function that returns matches for the current keyword.
-     * Called whenever the keyword changes (after debounce if configured).
-     */
-    getMatches: (context: {keyword: string}) => ReadonlyArray<TMatch>
-  }
-
+type GetMatches<TMatch extends object> = (context: {
+  keyword: string;
+}) => ReadonlyArray<TMatch> | Promise<ReadonlyArray<TMatch>>;
 /**
- * Action set that runs when the picker is dismissed.
- * Returns an array of behavior actions to execute (optional cleanup).
+ * Event passed to `onSelect` when a match is selected.
  *
  * @public
  */
-export declare type TypeaheadDismissActionSet = BehaviorActionSet<
-  TypeaheadDismissEvent,
-  true
->
-
+type TypeaheadSelectEvent<TMatch> = {
+  type: 'custom.typeahead select';
+  /** The match that was selected */
+  match: TMatch;
+  /** The extracted keyword (e.g., `joy` from `:joy`) */
+  keyword: string;
+  /** Selection range covering the full pattern match (e.g., `:joy`) for replacement */
+  patternSelection: NonNullable<EditorSelection>;
+};
 /**
  * Event passed to `onDismiss` when the picker is dismissed.
  *
  * @public
  */
-export declare type TypeaheadDismissEvent = {
-  type: 'custom.typeahead dismiss'
+type TypeaheadDismissEvent = {
+  type: 'custom.typeahead dismiss';
   /** Selection range covering the full pattern match (e.g., `@john`) for cleanup */
-  patternSelection: NonNullable<EditorSelection>
-}
-
+  patternSelection: NonNullable<EditorSelection>;
+};
 /**
- * The picker instance returned by {@link useTypeaheadPicker}.
- *
- * Provides a state machine-like interface for building picker UI:
- * - Use `snapshot.matches()` to check the current state and render accordingly
- * - Use `snapshot.context` to access the keyword, matches, and selected index
- * - Use `send()` to dispatch events like select, dismiss, or navigate
- *
- * @example
- * ```tsx
- * function EmojiPicker() {
- *   const picker = useTypeaheadPicker(emojiPickerDefinition)
- *
- *   if (picker.snapshot.matches('idle')) return null
- *   if (picker.snapshot.matches({active: 'loading'})) return <Spinner />
- *   if (picker.snapshot.matches({active: 'no matches'})) return <NoResults />
- *
- *   const {matches, selectedIndex} = picker.snapshot.context
+ * Action set that runs when a match is selected.
+ * Returns an array of behavior actions to execute (e.g., delete trigger text, insert content).
  *
- *   return (
- *     <ul>
- *       {matches.map((match, i) => (
- *         <li
- *           key={match.key}
- *           aria-selected={i === selectedIndex}
- *           onMouseEnter={() => picker.send({type: 'navigate to', index: i})}
- *           onClick={() => picker.send({type: 'select'})}
- *         >
- *           {match.emoji} {match.shortcode}
- *         </li>
- *       ))}
- *     </ul>
- *   )
- * }
- * ```
+ * @public
+ */
+type TypeaheadSelectActionSet<TMatch> = BehaviorActionSet<TypeaheadSelectEvent<TMatch>, true>;
+/**
+ * Action set that runs when the picker is dismissed.
+ * Returns an array of behavior actions to execute (optional cleanup).
  *
  * @public
  */
-export declare type TypeaheadPicker<TMatch extends object> = {
-  snapshot: {
-    /**
-     * Check if the picker is in a specific state.
-     * @see {@link TypeaheadPickerState} for available states
-     */
-    matches: (state: TypeaheadPickerState) => boolean
-    /**
-     * Current picker data including keyword, matches, and selection.
-     */
-    context: TypeaheadPickerContext<TMatch>
-  }
-  /**
-   * Dispatch an event to the picker.
-   * @see {@link TypeaheadPickerEvent} for available events
-   */
-  send: (event: TypeaheadPickerEvent) => void
-}
-
+type TypeaheadDismissActionSet = BehaviorActionSet<TypeaheadDismissEvent, true>;
 /**
- * Current picker data, accessible via `snapshot.context`.
+ * Event passed to the trigger guard when the picker is about to activate.
  *
  * @public
  */
-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: ReadonlyArray<TMatch>
-  /** Index of the currently selected match (for keyboard navigation and highlighting) */
-  selectedIndex: number
-  /** Error from `getMatches` if it threw, otherwise `undefined` */
-  error: Error | undefined
-}
-
+type TypeaheadTriggerEvent = {
+  type: 'custom.typeahead trigger found';
+};
 /**
- * Configuration object that defines a typeahead picker's behavior.
+ * Guard function that runs at trigger time to conditionally prevent the picker
+ * from activating. Has the same signature as a behavior guard.
  *
- * Create using {@link (defineTypeaheadPicker:1)} and pass to {@link useTypeaheadPicker}.
+ * Return `false` to block activation, or `true` to allow it.
  *
  * @example
  * ```ts
- * const emojiPicker = defineTypeaheadPicker({
- *   trigger: /:/,
- *   keyword: /[\S]+/,
- *   delimiter: ':',
- *   getMatches: ({keyword}) => searchEmojis(keyword),
- *   onSelect: [
- *     ({event}) => [
- *       raise({type: 'delete', at: event.patternSelection}),
- *       raise({type: 'insert.text', text: event.match.emoji}),
- *     ],
- *   ],
- * })
+ * guard: ({snapshot, event, dom}) => {
+ *   // Block activation if another picker is open
+ *   if (anotherPickerIsOpen()) return false
+ *
+ *   // Allow activation
+ *   return true
+ * }
  * ```
  *
  * @public
  */
-export declare type TypeaheadPickerDefinition<TMatch extends object = object> =
-  TypeaheadPickerDefinitionBase<TMatch> & {
-    /** @internal Unique identifier for this picker definition */
-    readonly _id: string
-    /**
-     * Whether `getMatches` returns synchronously or asynchronously.
-     * @defaultValue `'sync'`
-     */
-    mode?: 'sync' | 'async'
-    /**
-     * Debounce delay in milliseconds before calling `getMatches`.
-     * Useful for both async (API calls) and sync (expensive local search) modes.
-     * @defaultValue `0` (no debounce)
-     * @example `debounceMs: 200` - wait 200ms after last keystroke
-     */
-    debounceMs?: number
-    /**
-     * Function that retrieves matches for the current keyword.
-     * Use the `debounceMs` option to reduce calls during rapid typing.
-     */
-    getMatches: GetMatches<TMatch>
-  }
-
-declare type TypeaheadPickerDefinitionBase<TMatch extends object> = {
+type TypeaheadTriggerGuard = BehaviorGuard<TypeaheadTriggerEvent, true>;
+type TypeaheadPickerDefinitionBase<TMatch extends object> = {
   /**
    * Pattern that activates the picker.
    * Can include positional anchors like `^` for start-of-block triggers.
@@ -434,7 +127,7 @@ declare type TypeaheadPickerDefinitionBase<TMatch extends object> = {
    * @example `/@/` for mentions
    * @example `/^\//` for slash commands (start of block only)
    */
-  trigger: RegExp
+  trigger: RegExp;
   /**
    * Pattern matching the keyword portion (after trigger, before delimiter).
    * The entire match is used as the keyword.
@@ -442,14 +135,14 @@ declare type TypeaheadPickerDefinitionBase<TMatch extends object> = {
    * @example `/[\S]+/` for emoji (any non-whitespace)
    * @example `/[\w]+/` for mentions (word characters only)
    */
-  keyword: RegExp
+  keyword: RegExp;
   /**
    * 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
    */
-  delimiter?: string
+  delimiter?: string;
   /**
    * Guard function that runs at trigger time to conditionally prevent the picker
    * from activating.
@@ -457,7 +150,7 @@ declare type TypeaheadPickerDefinitionBase<TMatch extends object> = {
    *
    * @see {@link TypeaheadTriggerGuard}
    */
-  guard?: TypeaheadTriggerGuard
+  guard?: TypeaheadTriggerGuard;
   /**
    * Called when a match is selected.
    * Returns behavior actions to execute (e.g., delete trigger text, insert content).
@@ -472,14 +165,57 @@ declare type TypeaheadPickerDefinitionBase<TMatch extends object> = {
    * ]
    * ```
    */
-  onSelect: TypeaheadSelectActionSet<TMatch>[]
+  onSelect: TypeaheadSelectActionSet<TMatch>[];
   /**
    * Called when the picker is dismissed (Escape, cursor movement, etc.).
    * Returns behavior actions to execute (optional cleanup).
    */
-  onDismiss?: TypeaheadDismissActionSet[]
-}
-
+  onDismiss?: TypeaheadDismissActionSet[];
+};
+/**
+ * Configuration object that defines a typeahead picker's behavior.
+ *
+ * Create using {@link (defineTypeaheadPicker:1)} and pass to {@link useTypeaheadPicker}.
+ *
+ * @example
+ * ```ts
+ * const emojiPicker = defineTypeaheadPicker({
+ *   trigger: /:/,
+ *   keyword: /[\S]+/,
+ *   delimiter: ':',
+ *   getMatches: ({keyword}) => searchEmojis(keyword),
+ *   onSelect: [
+ *     ({event}) => [
+ *       raise({type: 'delete', at: event.patternSelection}),
+ *       raise({type: 'insert.text', text: event.match.emoji}),
+ *     ],
+ *   ],
+ * })
+ * ```
+ *
+ * @public
+ */
+type TypeaheadPickerDefinition<TMatch extends object = object> = TypeaheadPickerDefinitionBase<TMatch> & {
+  /** @internal Unique identifier for this picker definition */
+  readonly _id: string;
+  /**
+   * Whether `getMatches` returns synchronously or asynchronously.
+   * @defaultValue `'sync'`
+   */
+  mode?: 'sync' | 'async';
+  /**
+   * Debounce delay in milliseconds before calling `getMatches`.
+   * Useful for both async (API calls) and sync (expensive local search) modes.
+   * @defaultValue `0` (no debounce)
+   * @example `debounceMs: 200` - wait 200ms after last keystroke
+   */
+  debounceMs?: number;
+  /**
+   * Function that retrieves matches for the current keyword.
+   * Use the `debounceMs` option to reduce calls during rapid typing.
+   */
+  getMatches: GetMatches<TMatch>;
+};
 /**
  * Events that can be sent to the picker via `send()`.
  *
@@ -489,18 +225,14 @@ declare type TypeaheadPickerDefinitionBase<TMatch extends object> = {
  *
  * @public
  */
-export declare type TypeaheadPickerEvent =
-  | {
-      type: 'select'
-    }
-  | {
-      type: 'dismiss'
-    }
-  | {
-      type: 'navigate to'
-      index: number
-    }
-
+type TypeaheadPickerEvent = {
+  type: 'select';
+} | {
+  type: 'dismiss';
+} | {
+  type: 'navigate to';
+  index: number;
+};
 /**
  * Possible states for the picker, used with `snapshot.matches()`.
  *
@@ -529,88 +261,306 @@ export declare type TypeaheadPickerEvent =
  *
  * @public
  */
-export declare type TypeaheadPickerState =
-  | 'idle'
-  | 'active'
-  | {
-      active: 'loading'
-    }
-  | {
-      active: 'no matches'
-    }
-  | {
-      active: {
-        'no matches': 'loading'
-      }
-    }
-  | {
-      active: 'showing matches'
-    }
-  | {
-      active: {
-        'showing matches': 'loading'
-      }
-    }
-
+type TypeaheadPickerState = 'idle' | 'active' | {
+  active: 'loading';
+} | {
+  active: 'no matches';
+} | {
+  active: {
+    'no matches': 'loading';
+  };
+} | {
+  active: 'showing matches';
+} | {
+  active: {
+    'showing matches': 'loading';
+  };
+};
 /**
- * Action set that runs when a match is selected.
- * Returns an array of behavior actions to execute (e.g., delete trigger text, insert content).
+ * Current picker data, accessible via `snapshot.context`.
  *
  * @public
  */
-export declare type TypeaheadSelectActionSet<TMatch> = BehaviorActionSet<
-  TypeaheadSelectEvent<TMatch>,
-  true
->
-
+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: ReadonlyArray<TMatch>;
+  /** Index of the currently selected match (for keyboard navigation and highlighting) */
+  selectedIndex: number;
+  /** Error from `getMatches` if it threw, otherwise `undefined` */
+  error: Error | undefined;
+};
 /**
- * Event passed to `onSelect` when a match is selected.
+ * The picker instance returned by {@link useTypeaheadPicker}.
  *
- * @public
- */
-export declare type TypeaheadSelectEvent<TMatch> = {
-  type: 'custom.typeahead select'
-  /** The match that was selected */
-  match: TMatch
-  /** The extracted keyword (e.g., `joy` from `:joy`) */
-  keyword: string
-  /** Selection range covering the full pattern match (e.g., `:joy`) for replacement */
-  patternSelection: NonNullable<EditorSelection>
-}
-
-/**
- * Event passed to the trigger guard when the picker is about to activate.
+ * Provides a state machine-like interface for building picker UI:
+ * - Use `snapshot.matches()` to check the current state and render accordingly
+ * - Use `snapshot.context` to access the keyword, matches, and selected index
+ * - Use `send()` to dispatch events like select, dismiss, or navigate
+ *
+ * @example
+ * ```tsx
+ * function EmojiPicker() {
+ *   const picker = useTypeaheadPicker(emojiPickerDefinition)
+ *
+ *   if (picker.snapshot.matches('idle')) return null
+ *   if (picker.snapshot.matches({active: 'loading'})) return <Spinner />
+ *   if (picker.snapshot.matches({active: 'no matches'})) return <NoResults />
+ *
+ *   const {matches, selectedIndex} = picker.snapshot.context
+ *
+ *   return (
+ *     <ul>
+ *       {matches.map((match, i) => (
+ *         <li
+ *           key={match.key}
+ *           aria-selected={i === selectedIndex}
+ *           onMouseEnter={() => picker.send({type: 'navigate to', index: i})}
+ *           onClick={() => picker.send({type: 'select'})}
+ *         >
+ *           {match.emoji} {match.shortcode}
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   )
+ * }
+ * ```
  *
  * @public
  */
-export declare type TypeaheadTriggerEvent = {
-  type: 'custom.typeahead trigger found'
-}
-
+type TypeaheadPicker<TMatch extends object> = {
+  snapshot: {
+    /**
+     * Check if the picker is in a specific state.
+     * @see {@link TypeaheadPickerState} for available states
+     */
+    matches: (state: TypeaheadPickerState) => boolean;
+    /**
+     * Current picker data including keyword, matches, and selection.
+     */
+    context: TypeaheadPickerContext<TMatch>;
+  };
+  /**
+   * Dispatch an event to the picker.
+   * @see {@link TypeaheadPickerEvent} for available events
+   */
+  send: (event: TypeaheadPickerEvent) => void;
+};
+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;
+  /**
+   * Guard function that runs at trigger time to conditionally prevent activation.
+   * Return `false` to block activation, or `true` to allow it.
+   */
+  guard?: TypeaheadTriggerGuard;
+  /**
+   * Called when a match is selected.
+   * Returns behavior actions to execute (e.g., delete trigger text, insert content).
+   */
+  onSelect: TypeaheadSelectActionSet<TMatch>[];
+  /**
+   * Called when the picker is dismissed.
+   * Returns behavior actions to execute (optional cleanup).
+   */
+  onDismiss?: TypeaheadDismissActionSet[];
+};
+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;
+  /**
+   * Guard function that runs at trigger time to conditionally prevent activation.
+   * Return `false` to block activation, or `true` to allow it.
+   */
+  guard?: TypeaheadTriggerGuard;
+  /**
+   * Called when a match is selected.
+   * Returns behavior actions to execute (e.g., delete trigger text, insert content).
+   */
+  onSelect: TypeaheadSelectActionSet<TMatch>[];
+  /**
+   * Called when the picker is dismissed.
+   * Returns behavior actions to execute (optional cleanup).
+   */
+  onDismiss?: TypeaheadDismissActionSet[];
+};
+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;
+  /**
+   * Function that returns matches for the current keyword.
+   * Called whenever the keyword changes (after debounce if configured).
+   */
+  getMatches: (context: {
+    keyword: string;
+  }) => ReadonlyArray<TMatch>;
+};
+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;
+  /**
+   * Function that returns matches for the current keyword.
+   * Called whenever the keyword changes (after debounce if configured).
+   */
+  getMatches: (context: {
+    keyword: string;
+  }) => ReadonlyArray<TMatch>;
+};
+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;
+  /**
+   * 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>>;
+};
+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;
+  /**
+   * 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>>;
+};
 /**
- * Guard function that runs at trigger time to conditionally prevent the picker
- * from activating. Has the same signature as a behavior guard.
+ * Creates a typeahead picker definition to use with {@link useTypeaheadPicker}.
  *
- * Return `false` to block activation, or `true` to allow it.
+ * @example Emoji picker with auto-complete
+ * ```ts
+ * const emojiPicker = defineTypeaheadPicker({
+ *   trigger: /:/,
+ *   keyword: /[\S]+/,
+ *   delimiter: ':',
+ *   getMatches: ({keyword}) => searchEmojis(keyword),
+ *   onSelect: [
+ *     ({event}) => [
+ *       raise({type: 'delete', at: event.patternSelection}),
+ *       raise({type: 'insert.text', text: event.match.emoji}),
+ *     ],
+ *   ],
+ * })
+ * ```
  *
- * @example
+ * @example Async mention picker
  * ```ts
- * guard: ({snapshot, event, dom}) => {
- *   // Block activation if another picker is open
- *   if (anotherPickerIsOpen()) return false
+ * const mentionPicker = defineTypeaheadPicker({
+ *   mode: 'async',
+ *   trigger: /@/,
+ *   keyword: /[\w]+/,
+ *   debounceMs: 200,
+ *   getMatches: async ({keyword}) => api.searchUsers(keyword),
+ *   onSelect: [
+ *     ({event}) => [
+ *       raise({type: 'delete', at: event.patternSelection}),
+ *       raise({type: 'insert.inline object', inlineObject: {_type: 'mention', userId: event.match.id}}),
+ *     ],
+ *   ],
+ * })
+ * ```
  *
- *   // Allow activation
- *   return true
- * }
+ * @example Picker with guard (runs at trigger time)
+ * ```ts
+ * const emojiPicker = defineTypeaheadPicker({
+ *   trigger: /:/,
+ *   keyword: /[\S]+/,
+ *   getMatches: ({keyword}) => searchEmojis(keyword),
+ *   guard: ({snapshot, event, dom}) => {
+ *     if (anotherPickerIsOpen()) return false
+ *     return true
+ *   },
+ *   onSelect: [
+ *     ({event}) => [
+ *       raise({type: 'delete', at: event.patternSelection}),
+ *       raise({type: 'insert.text', text: event.match.emoji}),
+ *     ],
+ *   ],
+ * })
  * ```
  *
  * @public
  */
-export declare type TypeaheadTriggerGuard = BehaviorGuard<
-  TypeaheadTriggerEvent,
-  true
->
-
+declare function defineTypeaheadPicker<TMatch extends object>(config: SyncConfigWithoutDelimiter<TMatch>): TypeaheadPickerDefinition<TMatch>;
+/** @public */
+declare function defineTypeaheadPicker<TMatch extends AutoCompleteMatch>(config: SyncConfigWithDelimiter<TMatch>): TypeaheadPickerDefinition<TMatch>;
+/** @public */
+declare function defineTypeaheadPicker<TMatch extends object>(config: AsyncConfigWithoutDelimiter<TMatch>): TypeaheadPickerDefinition<TMatch>;
+/** @public */
+declare function defineTypeaheadPicker<TMatch extends AutoCompleteMatch>(config: AsyncConfigWithDelimiter<TMatch>): TypeaheadPickerDefinition<TMatch>;
 /**
  * React hook that activates a typeahead picker and returns its current state.
  *
@@ -647,8 +597,6 @@ export declare type TypeaheadTriggerGuard = BehaviorGuard<
  *
  * @public
  */
-export declare function useTypeaheadPicker<TMatch extends object>(
-  definition: TypeaheadPickerDefinition<TMatch>,
-): TypeaheadPicker<TMatch>
-
-export {}
+declare function useTypeaheadPicker<TMatch extends object>(definition: TypeaheadPickerDefinition<TMatch>): TypeaheadPicker<TMatch>;
+export { type AutoCompleteMatch, type GetMatches, type TypeaheadDismissActionSet, type TypeaheadDismissEvent, type TypeaheadPicker, type TypeaheadPickerContext, type TypeaheadPickerDefinition, type TypeaheadPickerEvent, type TypeaheadPickerState, type TypeaheadSelectActionSet, type TypeaheadSelectEvent, type TypeaheadTriggerEvent, type TypeaheadTriggerGuard, defineTypeaheadPicker, useTypeaheadPicker };
+//# sourceMappingURL=index.d.ts.map