@portabletext/plugin-typeahead-picker 2.1.0 → 3.0.1

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':
@@ -204,7 +204,7 @@ const emojiPicker = defineTypeaheadPicker<EmojiMatch>({
     return true
   },
 
-  actions: [
+  onSelect: [
     ({event}) => [
       raise({type: 'delete', at: event.patternSelection}),
       raise({type: 'insert.text', text: event.match.emoji}),
@@ -235,7 +235,8 @@ Creates a picker definition to pass to `useTypeaheadPicker`.
 | `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:**
 
@@ -352,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(
@@ -383,7 +427,7 @@ const commandPicker = defineTypeaheadPicker<CommandMatch>({
 })
 ```
 
-**Action payload:**
+**onSelect payload:**
 
 | Property   | Description                                                                   |
 | ---------- | ----------------------------------------------------------------------------- |
@@ -515,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

@@ -98,10 +98,15 @@ declare type BaseConfigWithDelimiter<TMatch extends AutoCompleteMatch> = {
    */
   guard?: TypeaheadTriggerGuard
   /**
-   * Actions to execute when a match is selected.
-   * Typically deletes the trigger text and inserts the selected content.
+   * Called when a match is selected.
+   * Returns behavior actions to execute (e.g., delete trigger text, insert content).
    */
-  actions: Array<TypeaheadSelectActionSet<TMatch>>
+  onSelect: TypeaheadSelectActionSet<TMatch>[]
+  /**
+   * Called when the picker is dismissed.
+   * Returns behavior actions to execute (optional cleanup).
+   */
+  onDismiss?: TypeaheadDismissActionSet[]
 }
 
 declare type BaseConfigWithoutDelimiter<TMatch extends object> = {
@@ -127,10 +132,15 @@ declare type BaseConfigWithoutDelimiter<TMatch extends object> = {
    */
   guard?: TypeaheadTriggerGuard
   /**
-   * Actions to execute when a match is selected.
-   * Typically deletes the trigger text and inserts the selected content.
+   * 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[]
 }
 
 /**
@@ -143,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}),
+ *     ],
+ *   ],
  * })
  * ```
  *
@@ -155,17 +170,12 @@ declare type BaseConfigWithoutDelimiter<TMatch extends object> = {
  *   keyword: /[\w]+/,
  *   debounceMs: 200,
  *   getMatches: async ({keyword}) => api.searchUsers(keyword),
- *   actions: [insertMentionAction],
- * })
- * ```
- *
- * @example Slash commands at start of block
- * ```ts
- * const slashCommandPicker = defineTypeaheadPicker({
- *   trigger: /^\//,
- *   keyword: /[\w]+/,
- *   getMatches: ({keyword}) => filterCommands(keyword),
- *   actions: [executeCommandAction],
+ *   onSelect: [
+ *     ({event}) => [
+ *       raise({type: 'delete', at: event.patternSelection}),
+ *       raise({type: 'insert.inline object', inlineObject: {_type: 'mention', userId: event.match.id}}),
+ *     ],
+ *   ],
  * })
  * ```
  *
@@ -175,15 +185,16 @@ declare type BaseConfigWithoutDelimiter<TMatch extends object> = {
  *   trigger: /:/,
  *   keyword: /[\S]+/,
  *   getMatches: ({keyword}) => searchEmojis(keyword),
- *   guard: ({snapshot}) => {
- *     // Return false to prevent picker from activating
+ *   guard: ({snapshot, event, dom}) => {
  *     if (anotherPickerIsOpen()) return false
  *     return true
  *   },
- *   actions: [({event}) => [
- *     raise({type: 'delete', at: event.patternSelection}),
- *     raise({type: 'insert.text', text: event.match.emoji}),
- *   ]],
+ *   onSelect: [
+ *     ({event}) => [
+ *       raise({type: 'delete', at: event.patternSelection}),
+ *       raise({type: 'insert.text', text: event.match.emoji}),
+ *     ],
+ *   ],
  * })
  * ```
  *
@@ -275,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}.
  *
@@ -360,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}),
+ *     ],
+ *   ],
  * })
  * ```
  *
@@ -369,7 +407,7 @@ export declare type TypeaheadPickerContext<TMatch> = {
 export declare type TypeaheadPickerDefinition<TMatch extends object = object> =
   TypeaheadPickerDefinitionBase<TMatch> & {
     /** @internal Unique identifier for this picker definition */
-    readonly _id: symbol
+    readonly _id: string
     /**
      * Whether `getMatches` returns synchronously or asynchronously.
      * @defaultValue `'sync'`
@@ -423,12 +461,25 @@ declare type TypeaheadPickerDefinitionBase<TMatch extends object> = {
    */
   guard?: TypeaheadTriggerGuard
   /**
-   * Actions to execute when a match is selected.
-   * Typically deletes the trigger text and inserts the selected content.
+   * 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[]
 }
 
 /**
@@ -504,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<
@@ -525,7 +566,7 @@ export declare type TypeaheadSelectActionSet<TMatch> = BehaviorActionSet<
 >
 
 /**
- * Event passed to typeahead select action sets.
+ * Event passed to `onSelect` when a match is selected.
  *
  * @public
  */