@portabletext/plugin-typeahead-picker 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2016 - 2026 Sanity.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,495 @@
+# `@portabletext/plugin-typeahead-picker`
+
+> Generic typeahead picker infrastructure for the Portable Text Editor
+
+## Quick Start
+
+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 {raise} from '@portabletext/editor/behaviors'
+import {
+  defineTypeaheadPicker,
+  useTypeaheadPicker,
+  type AutoCompleteMatch,
+} from '@portabletext/plugin-typeahead-picker'
+
+// With `autoCompleteWith` configured, matches must include `type: 'exact' | 'partial'`
+// for auto-completion to work. Use `AutoCompleteMatch` as the base type.
+type EmojiMatch = AutoCompleteMatch & {
+  key: string
+  emoji: string
+  shortcode: string
+}
+
+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*)/,
+
+  // Optional autoCompleteWith enables auto-completion.
+  // Typing `:joy:` will auto-insert if "joy" is an exact match.
+  autoCompleteWith: ':',
+
+  // 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).
+  // Receives the event containing the selected match and pattern selection.
+  actions: [
+    ({event}) => [
+      raise({type: 'delete', at: event.patternSelection}), // Delete `:joy`
+      raise({type: 'insert.text', text: event.match.emoji}), // Insert 😂
+    ],
+  ],
+})
+
+function EmojiPicker() {
+  // Activate the picker and get its current state
+  const picker = useTypeaheadPicker(emojiPicker)
+
+  // Don't render anything when picker is inactive
+  if (picker.snapshot.matches('idle')) {
+    return null
+  }
+
+  const {keyword, matches, selectedIndex} = picker.snapshot.context
+
+  if (matches.length === 0) {
+    return <div>No emojis found for "{keyword}"</div>
+  }
+
+  return (
+    <ul>
+      {matches.map((match, index) => (
+        <li
+          key={match.key}
+          aria-selected={index === selectedIndex}
+          // Optional: enable mouse hover to select
+          onMouseEnter={() => picker.send({type: 'navigate to', index})}
+          // Optional: enable click to insert
+          onClick={() => picker.send({type: 'select'})}
+        >
+          {match.emoji} {match.shortcode}
+        </li>
+      ))}
+    </ul>
+  )
+}
+```
+
+## How It Works
+
+The picker activates when users type text matching the `pattern` (e.g., `:smile` or `@john`).
+
+- **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)
+
+## Examples
+
+### Emoji picker
+
+```ts
+const emojiPicker = defineTypeaheadPicker<EmojiMatch>({
+  pattern: /:(\S*)/,
+  autoCompleteWith: ':',
+  getMatches: ({keyword}) => searchEmojis(keyword),
+  actions: [
+    ({event}) => [
+      raise({type: 'delete', at: event.patternSelection}),
+      raise({type: 'insert.text', text: event.match.emoji}),
+    ],
+  ],
+})
+```
+
+`:joy:` auto-inserts the emoji
+
+### Mention picker (async with debounce)
+
+```ts
+// Without `autoCompleteWith`, the `type` field is not required on matches.
+// MentionMatch can just be: { id: string; name: string }
+const mentionPicker = defineTypeaheadPicker<MentionMatch>({
+  mode: 'async',
+  pattern: /@(\w*)/,
+  debounceMs: 200,
+  getMatches: async ({keyword}) => api.searchUsers(keyword),
+  actions: [
+    ({event}) => [
+      raise({type: 'delete', at: event.patternSelection}),
+      raise({
+        type: 'insert.child',
+        child: {_type: 'mention', userId: event.match.id},
+      }),
+    ],
+  ],
+})
+```
+
+`@john` shows matches after 200ms pause, user selects with Enter/Tab
+
+### Slash command picker (start of block only)
+
+```ts
+// Without `autoCompleteWith`, the `type` field is not required on matches.
+const commandPicker = defineTypeaheadPicker<CommandMatch>({
+  pattern: /^\/(\w*)/, // ^ anchors to start of block
+  getMatches: ({keyword}) => searchCommands(keyword),
+  actions: [
+    ({event}) => {
+      switch (event.match.command) {
+        case 'h1':
+        case 'h2':
+        case 'h3':
+          return [
+            raise({type: 'delete', at: event.patternSelection}),
+            raise({type: 'style.toggle', style: event.match.command}),
+          ]
+        case 'image':
+          return [
+            raise({type: 'delete', at: event.patternSelection}),
+            raise({type: 'insert.block', block: {_type: 'image'}}),
+          ]
+        default:
+          return [raise({type: 'delete', at: event.patternSelection})]
+      }
+    },
+  ],
+})
+```
+
+`/heading` shows matching commands, but only when `/` is at the start of a block. Text like `hello /heading` will NOT trigger the picker.
+
+## API Reference
+
+### `defineTypeaheadPicker(config)`
+
+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                                                                                                                                    |
+
+**Pattern rules:**
+
+- If pattern has capture groups: keyword = first capture group
+- If no capture group: keyword = entire match
+- 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:
+
+```
+User types `:` → Pattern /:(\S*)/ 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:**
+
+| 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   |
+
+**autoCompleteWith requirements:**
+
+When using `autoCompleteWith`, the delimiter character must be included in the keyword's character class, otherwise typing it dismisses the picker:
+
+| 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 |
+
+### `useTypeaheadPicker(definition)`
+
+React hook that activates a picker and returns its state.
+
+**Returns:**
+
+| 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.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}`                     |
+| `snapshot.context.error`         | Error from `getMatches` if it threw/rejected, otherwise `undefined`                                          |
+
+## Async Mode
+
+When `mode: 'async'` is configured, the picker handles asynchronous `getMatches` functions with loading states and race condition protection.
+
+### Loading States
+
+Use `snapshot.matches()` to check nested loading states:
+
+```tsx
+function MentionPicker() {
+  const picker = useTypeaheadPicker(mentionPicker)
+
+  // Initial loading (no results yet)
+  const isLoading = picker.snapshot.matches({active: 'loading'})
+
+  // Background refresh (showing stale results while fetching new ones)
+  const isRefreshing = picker.snapshot.matches({
+    active: {'showing matches': 'loading'},
+  })
+
+  // No matches, but still fetching (to avoid flicker)
+  const isLoadingNoMatches = picker.snapshot.matches({
+    active: {'no matches': 'loading'},
+  })
+
+  if (isLoading) return <Spinner />
+  if (picker.snapshot.matches({active: 'no matches'})) return <NoResults />
+
+  return (
+    <MatchList isRefreshing={isRefreshing}>
+      {picker.snapshot.context.matches.map(/* ... */)}
+    </MatchList>
+  )
+}
+```
+
+### Race Condition Handling
+
+When users type quickly, earlier slow requests may complete after later fast requests. The picker automatically ignores stale results to prevent them from overwriting fresh data.
+
+## Error Handling
+
+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() {
+  const picker = useTypeaheadPicker(emojiPicker)
+  const {error} = picker.snapshot.context
+
+  if (error) {
+    return (
+      <div>
+        <p>Failed to load: {error.message}</p>
+        <button onClick={() => picker.send({type: 'dismiss'})}>Dismiss</button>
+      </div>
+    )
+  }
+
+  // ... render matches
+}
+```
+
+The error is cleared when the picker returns to idle (e.g., via Escape or cursor movement).
+
+## Advanced Actions
+
+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.
+
+```tsx
+const commandPicker = defineTypeaheadPicker<CommandMatch>({
+  pattern: /^\/(\w*)/,
+  getMatches: ({keyword}) => searchCommands(keyword),
+  actions: [
+    ({event, snapshot}) => {
+      // Access schema to check for block object fields
+      const blockObjectSchema = snapshot.context.schema.blockObjects.find(
+        (bo) => bo.name === event.match.blockType,
+      )
+
+      // Generate unique keys for inserted blocks
+      const blockKey = snapshot.context.keyGenerator()
+
+      return [
+        raise({type: 'delete', at: event.patternSelection}),
+        raise({
+          type: 'insert.block',
+          block: {_type: event.match.blockType, _key: blockKey},
+        }),
+      ]
+    },
+  ],
+})
+```
+
+**Action payload:**
+
+| Property   | Description                                                                   |
+| ---------- | ----------------------------------------------------------------------------- |
+| `event`    | The select event with `match`, `keyword`, and `patternSelection`              |
+| `snapshot` | Current editor snapshot with `context.schema`, `context.keyGenerator()`, etc. |
+
+## Performance Guidelines
+
+### Match List Size
+
+Keep your match lists reasonably sized for smooth keyboard navigation:
+
+- **Recommended**: Return 10-50 matches maximum
+- **Large datasets**: Filter on the server or use pagination
+- **Infinite lists**: Consider virtualizing if rendering many items
+
+```tsx
+getMatches: async ({keyword}) => {
+  const results = await api.searchUsers(keyword)
+  return results.slice(0, 20) // Limit to 20 matches
+}
+```
+
+### Debounce Timing
+
+Choose debounce values based on your data source:
+
+| Source                         | Recommended `debounceMs` |
+| ------------------------------ | ------------------------ |
+| Local array filter             | `0` (no debounce)        |
+| Expensive local Fuse.js search | `50-100`                 |
+| Fast API endpoint              | `150-200`                |
+| Slow API endpoint              | `200-300`                |
+
+```tsx
+// Local data - no debounce needed
+const emojiPicker = defineTypeaheadPicker({
+  pattern: /:(\S*)/,
+  getMatches: ({keyword}) => filterEmojis(keyword), // Fast local filter
+  // ...
+})
+
+// API data - debounce to reduce requests
+const mentionPicker = defineTypeaheadPicker({
+  mode: 'async',
+  debounceMs: 200,
+  pattern: /@(\w*)/,
+  getMatches: async ({keyword}) => api.searchUsers(keyword),
+  // ...
+})
+```
+
+### Memory Considerations
+
+- Avoid storing large datasets in component state
+- For emoji pickers, consider lazy-loading the emoji database
+- Clean up listeners when components unmount (the hook handles this automatically)
+
+## Accessibility
+
+The picker manages keyboard navigation and selection internally, but you're responsible for the UI semantics.
+
+### Recommended ARIA Attributes
+
+```tsx
+function PickerUI() {
+  const picker = useTypeaheadPicker(definition)
+  const {matches, selectedIndex} = picker.snapshot.context
+
+  return (
+    <ul role="listbox" aria-label="Suggestions">
+      {matches.map((match, index) => (
+        <li
+          key={match.key}
+          role="option"
+          aria-selected={index === selectedIndex}
+          onMouseEnter={() => picker.send({type: 'navigate to', index})}
+          onClick={() => picker.send({type: 'select'})}
+        >
+          {match.label}
+        </li>
+      ))}
+    </ul>
+  )
+}
+```
+
+### Keyboard Handling
+
+The following keyboard shortcuts are handled automatically by the picker:
+
+| Key       | Action                        |
+| --------- | ----------------------------- |
+| `↑` / `↓` | Navigate through matches      |
+| `Enter`   | Insert selected match         |
+| `Tab`     | Insert selected match         |
+| `Escape`  | Dismiss picker                |
+| `Space`   | Dismiss picker (configurable) |
+
+### Screen Reader Considerations
+
+- Announce match count changes with live regions if desired
+- Ensure selected item is visible (scroll into view)
+- Provide clear labels for what each match represents
+
+## Troubleshooting
+
+### 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 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
+
+### Auto-completion doesn't work
+
+- **Check `autoCompleteWith`**: Must be set (e.g., `autoCompleteWith: ':'`)
+- **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: ':'`
+
+### Stale matches appear
+
+- For async pickers, the race condition handling should prevent this automatically
+- If issues persist, check that `getMatches` doesn't cache results incorrectly
+
+### Focus issues after selection
+
+- Ensure your actions include focus restoration if needed:
+  ```tsx
+  actions: [
+    ({event}) => [
+      raise({type: 'delete', at: event.patternSelection}),
+      raise({type: 'insert.text', text: event.match.emoji}),
+    ],
+    () => [
+      effect(({send}) => {
+        send({type: 'focus'})
+      }),
+    ],
+  ]
+  ```