@portabletext/plugin-typeahead-picker 2.0.6 → 3.0.0

package/README.md

@@ -37,9 +37,9 @@ const emojiPicker = defineTypeaheadPicker<EmojiMatch>({
   // Return matches for the keyword. Can be sync or async (with mode: 'async').
   getMatches: ({keyword}) => searchEmojis(keyword),
 
-  // Actions to execute when a match is selected (Enter/Tab or click).
+  // Action to execute when a match is selected (Enter/Tab or click).
   // Receives the event containing the selected match and pattern selection.
-  actions: [
+  onSelect: [
     ({event}) => [
       raise({type: 'delete', at: event.patternSelection}), // Delete `:joy`
       raise({type: 'insert.text', text: event.match.emoji}), // Insert 😂
@@ -114,7 +114,7 @@ const emojiPicker = defineTypeaheadPicker<EmojiMatch>({
   keyword: /\S*/,
   delimiter: ':',
   getMatches: ({keyword}) => searchEmojis(keyword),
-  actions: [
+  onSelect: [
     ({event}) => [
       raise({type: 'delete', at: event.patternSelection}),
       raise({type: 'insert.text', text: event.match.emoji}),
@@ -136,7 +136,7 @@ const mentionPicker = defineTypeaheadPicker<MentionMatch>({
   keyword: /\w*/,
   debounceMs: 200,
   getMatches: async ({keyword}) => api.searchUsers(keyword),
-  actions: [
+  onSelect: [
     ({event}) => [
       raise({type: 'delete', at: event.patternSelection}),
       raise({
@@ -158,7 +158,7 @@ const commandPicker = defineTypeaheadPicker<CommandMatch>({
   trigger: /^\//, // ^ anchors to start of block
   keyword: /\w*/,
   getMatches: ({keyword}) => searchCommands(keyword),
-  actions: [
+  onSelect: [
     ({event}) => {
       switch (event.match.command) {
         case 'h1':
@@ -183,6 +183,41 @@ const commandPicker = defineTypeaheadPicker<CommandMatch>({
 
 `/heading` shows matching commands, but only when `/` is at the start of a block. Text like `hello /heading` will NOT trigger the picker.
 
+### Picker with guard
+
+Use `guard` to conditionally prevent the picker from activating. The guard runs at trigger time (when the trigger character is typed) and has the same signature as a behavior guard, receiving `snapshot`, `event`, and `dom`.
+
+```ts
+const emojiPicker = defineTypeaheadPicker<EmojiMatch>({
+  trigger: /:/,
+  keyword: /\S*/,
+  delimiter: ':',
+  getMatches: ({keyword}) => searchEmojis(keyword),
+
+  // Guard runs when `:` is typed - return false to block activation
+  guard: ({snapshot, event, dom}) => {
+    // Don't activate if another UI element is open
+    if (isDialogOpen()) {
+      return false
+    }
+
+    return true
+  },
+
+  onSelect: [
+    ({event}) => [
+      raise({type: 'delete', at: event.patternSelection}),
+      raise({type: 'insert.text', text: event.match.emoji}),
+    ],
+  ],
+})
+```
+
+The guard is useful for:
+
+- Avoiding conflicts when another picker or dialog is already open
+- Checking editor state or mode before allowing the picker
+
 ## API Reference
 
 ### `defineTypeaheadPicker(config)`
@@ -196,10 +231,12 @@ Creates a picker definition to pass to `useTypeaheadPicker`.
 | `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:`)                                                              |
+| `guard`      | `TypeaheadTriggerGuard?`               | Optional guard that runs at trigger time to conditionally prevent activation                                                            |
 | `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                                                                                             |
+| `onSelect`   | `TypeaheadSelectActionSet[]`           | Action sets to execute when a match is selected                                                                                         |
+| `onDismiss`  | `TypeaheadDismissActionSet[]?`         | Optional action sets to execute when the picker is dismissed                                                                            |
 
 **Trigger pattern rules:**
 
@@ -316,16 +353,59 @@ function EmojiPickerPlugin() {
 
 The error is cleared when the picker returns to idle (e.g., via Escape or cursor movement).
 
-## Advanced Actions
+## onDismiss
 
-Action functions receive more than just the event. The full payload includes access to the editor snapshot, which is useful for generating keys, accessing the schema, or reading the current editor state.
+The optional `onDismiss` callback runs when the picker is dismissed via Escape. This is useful for cleaning up the typed trigger and keyword text.
+
+```ts
+const mentionPicker = defineTypeaheadPicker<MentionMatch>({
+  trigger: /@/,
+  keyword: /\w*/,
+  getMatches: ({keyword}) => searchUsers(keyword),
+  onSelect: [
+    ({event}) => [
+      raise({type: 'delete', at: event.patternSelection}),
+      raise({type: 'insert.text', text: `@${event.match.name}`}),
+    ],
+  ],
+  // Delete the typed text when user presses Escape
+  onDismiss: [
+    ({event}) => [raise({type: 'delete', at: event.patternSelection})],
+  ],
+})
+```
+
+Without `onDismiss`, pressing Escape leaves the typed text in place (e.g., `@john` remains in the editor). With `onDismiss` configured to delete the pattern, the text is removed.
+
+**onDismiss payload:**
+
+| Property                 | Description                                                    |
+| ------------------------ | -------------------------------------------------------------- |
+| `event.patternSelection` | Selection range covering the trigger + keyword (e.g., `@john`) |
+| `snapshot`               | Current editor snapshot                                        |
+
+Note: `onDismiss` is called when the user actively dismisses the picker:
+
+- Pressing Escape
+- Pressing Enter/Tab when there are no matches
+- Programmatically via `picker.send({type: 'dismiss'})`
+
+It is NOT called when:
+
+- The user selects a match (Enter/Tab/click with a match selected)
+- The picker is dismissed due to cursor movement
+- The picker is dismissed due to invalid pattern (e.g., typing a space)
+
+## Advanced onSelect
+
+The `onSelect` callback receives more than just the event. The full payload includes access to the editor snapshot, which is useful for generating keys, accessing the schema, or reading the current editor state.
 
 ```tsx
 const commandPicker = defineTypeaheadPicker<CommandMatch>({
   trigger: /^\//,
   keyword: /\w*/,
   getMatches: ({keyword}) => searchCommands(keyword),
-  actions: [
+  onSelect: [
     ({event, snapshot}) => {
       // Access schema to check for block object fields
       const blockObjectSchema = snapshot.context.schema.blockObjects.find(
@@ -347,7 +427,7 @@ const commandPicker = defineTypeaheadPicker<CommandMatch>({
 })
 ```
 
-**Action payload:**
+**onSelect payload:**
 
 | Property   | Description                                                                   |
 | ---------- | ----------------------------------------------------------------------------- |
@@ -463,6 +543,7 @@ The following keyboard shortcuts are handled automatically by the picker:
 - **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**: Triggers like `/##/` don't work because the picker only activates on newly typed single characters
+- **Check guard**: If you have a `guard` configured, ensure it's returning `true` when activation should be allowed
 
 ### Auto-completion doesn't work
 
@@ -478,14 +559,12 @@ The following keyboard shortcuts are handled automatically by the picker:
 
 ### Focus issues after selection
 
-- Ensure your actions include focus restoration if needed:
+- Ensure your onSelect includes focus restoration if needed:
   ```tsx
-  actions: [
+  onSelect: [
     ({event}) => [
       raise({type: 'delete', at: event.patternSelection}),
       raise({type: 'insert.text', text: event.match.emoji}),
-    ],
-    () => [
       effect(({send}) => {
         send({type: 'focus'})
       }),

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 import type {EditorSelection} from '@portabletext/editor'
-import type {BehaviorActionSet} from '@portabletext/editor/behaviors'
+import type {
+  BehaviorActionSet,
+  BehaviorGuard,
+} from '@portabletext/editor/behaviors'
 
 declare type AsyncConfigWithDelimiter<TMatch extends AutoCompleteMatch> =
   BaseConfigWithDelimiter<TMatch> & {
@@ -90,10 +93,20 @@ declare type BaseConfigWithDelimiter<TMatch extends AutoCompleteMatch> = {
    */
   delimiter: string
   /**
-   * Actions to execute when a match is selected.
-   * Typically deletes the trigger text and inserts the selected content.
+   * Guard function that runs at trigger time to conditionally prevent activation.
+   * Return `false` to block activation, or `true` to allow it.
    */
-  actions: Array<TypeaheadSelectActionSet<TMatch>>
+  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> = {
@@ -114,10 +127,20 @@ declare type BaseConfigWithoutDelimiter<TMatch extends object> = {
   keyword: RegExp
   delimiter?: undefined
   /**
-   * Actions to execute when a match is selected.
-   * Typically deletes the trigger text and inserts the selected content.
+   * 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).
    */
-  actions: Array<TypeaheadSelectActionSet<TMatch>>
+  onDismiss?: TypeaheadDismissActionSet[]
 }
 
 /**
@@ -130,7 +153,12 @@ declare type BaseConfigWithoutDelimiter<TMatch extends object> = {
  *   keyword: /[\S]+/,
  *   delimiter: ':',
  *   getMatches: ({keyword}) => searchEmojis(keyword),
- *   actions: [insertEmojiAction],
+ *   onSelect: [
+ *     ({event}) => [
+ *       raise({type: 'delete', at: event.patternSelection}),
+ *       raise({type: 'insert.text', text: event.match.emoji}),
+ *     ],
+ *   ],
  * })
  * ```
  *
@@ -142,17 +170,31 @@ declare type BaseConfigWithoutDelimiter<TMatch extends object> = {
  *   keyword: /[\w]+/,
  *   debounceMs: 200,
  *   getMatches: async ({keyword}) => api.searchUsers(keyword),
- *   actions: [insertMentionAction],
+ *   onSelect: [
+ *     ({event}) => [
+ *       raise({type: 'delete', at: event.patternSelection}),
+ *       raise({type: 'insert.inline object', inlineObject: {_type: 'mention', userId: event.match.id}}),
+ *     ],
+ *   ],
  * })
  * ```
  *
- * @example Slash commands at start of block
+ * @example Picker with guard (runs at trigger time)
  * ```ts
- * const slashCommandPicker = defineTypeaheadPicker({
- *   trigger: /^\//,
- *   keyword: /[\w]+/,
- *   getMatches: ({keyword}) => filterCommands(keyword),
- *   actions: [executeCommandAction],
+ * 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}),
+ *     ],
+ *   ],
  * })
  * ```
  *
@@ -244,6 +286,28 @@ declare type SyncConfigWithoutDelimiter<TMatch extends object> =
     getMatches: (context: {keyword: string}) => ReadonlyArray<TMatch>
   }
 
+/**
+ * Action set that runs when the picker is dismissed.
+ * Returns an array of behavior actions to execute (optional cleanup).
+ *
+ * @public
+ */
+export declare type TypeaheadDismissActionSet = BehaviorActionSet<
+  TypeaheadDismissEvent,
+  true
+>
+
+/**
+ * Event passed to `onDismiss` when the picker is dismissed.
+ *
+ * @public
+ */
+export declare type TypeaheadDismissEvent = {
+  type: 'custom.typeahead dismiss'
+  /** Selection range covering the full pattern match (e.g., `@john`) for cleanup */
+  patternSelection: NonNullable<EditorSelection>
+}
+
 /**
  * The picker instance returned by {@link useTypeaheadPicker}.
  *
@@ -329,7 +393,12 @@ export declare type TypeaheadPickerContext<TMatch> = {
  *   keyword: /[\S]+/,
  *   delimiter: ':',
  *   getMatches: ({keyword}) => searchEmojis(keyword),
- *   actions: [insertEmojiAction],
+ *   onSelect: [
+ *     ({event}) => [
+ *       raise({type: 'delete', at: event.patternSelection}),
+ *       raise({type: 'insert.text', text: event.match.emoji}),
+ *     ],
+ *   ],
  * })
  * ```
  *
@@ -384,12 +453,33 @@ declare type TypeaheadPickerDefinitionBase<TMatch extends object> = {
    */
   delimiter?: string
   /**
-   * Actions to execute when a match is selected.
-   * Typically deletes the trigger text and inserts the selected content.
+   * Guard function that runs at trigger time to conditionally prevent the picker
+   * from activating.
+   * Return `false` to block activation, or `true` to allow it.
+   *
+   * @see {@link TypeaheadTriggerGuard}
+   */
+  guard?: TypeaheadTriggerGuard
+  /**
+   * Called when a match is selected.
+   * Returns behavior actions to execute (e.g., delete trigger text, insert content).
    *
-   * @see {@link TypeaheadSelectActionSet}
+   * @example
+   * ```ts
+   * onSelect: [
+   *   ({event}) => [
+   *     raise({type: 'delete', at: event.patternSelection}),
+   *     raise({type: 'insert.text', text: event.match.emoji}),
+   *   ],
+   * ]
+   * ```
+   */
+  onSelect: TypeaheadSelectActionSet<TMatch>[]
+  /**
+   * Called when the picker is dismissed (Escape, cursor movement, etc.).
+   * Returns behavior actions to execute (optional cleanup).
    */
-  actions: Array<TypeaheadSelectActionSet<TMatch>>
+  onDismiss?: TypeaheadDismissActionSet[]
 }
 
 /**
@@ -465,19 +555,9 @@ export declare type TypeaheadPickerState =
     }
 
 /**
- * Action function that runs when a match is selected.
+ * Action set that runs when a match is selected.
  * Returns an array of behavior actions to execute (e.g., delete trigger text, insert content).
  *
- * @example
- * ```ts
- * const insertEmoji: TypeaheadSelectActionSet<EmojiMatch> = (
- *   {event},
- * ) => [
- *   raise({type: 'delete', at: event.patternSelection}),
- *   raise({type: 'insert.text', text: event.match.emoji}),
- * ]
- * ```
- *
  * @public
  */
 export declare type TypeaheadSelectActionSet<TMatch> = BehaviorActionSet<
@@ -486,12 +566,12 @@ export declare type TypeaheadSelectActionSet<TMatch> = BehaviorActionSet<
 >
 
 /**
- * Event passed to typeahead select action sets.
+ * Event passed to `onSelect` when a match is selected.
  *
  * @public
  */
 export declare type TypeaheadSelectEvent<TMatch> = {
-  type: 'typeahead.select'
+  type: 'custom.typeahead select'
   /** The match that was selected */
   match: TMatch
   /** The extracted keyword (e.g., `joy` from `:joy`) */
@@ -500,6 +580,39 @@ export declare type TypeaheadSelectEvent<TMatch> = {
   patternSelection: NonNullable<EditorSelection>
 }
 
+/**
+ * Event passed to the trigger guard when the picker is about to activate.
+ *
+ * @public
+ */
+export declare type TypeaheadTriggerEvent = {
+  type: 'custom.typeahead trigger found'
+}
+
+/**
+ * Guard function that runs at trigger time to conditionally prevent the picker
+ * from activating. Has the same signature as a behavior guard.
+ *
+ * Return `false` to block activation, or `true` to allow it.
+ *
+ * @example
+ * ```ts
+ * guard: ({snapshot, event, dom}) => {
+ *   // Block activation if another picker is open
+ *   if (anotherPickerIsOpen()) return false
+ *
+ *   // Allow activation
+ *   return true
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare type TypeaheadTriggerGuard = BehaviorGuard<
+  TypeaheadTriggerEvent,
+  true
+>
+
 /**
  * React hook that activates a typeahead picker and returns its current state.
  *