@portabletext/plugin-emoji-picker 0.0.15 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2016 - 2025 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

@@ -1,3 +1,98 @@
 # `@portabletext/plugin-emoji-picker`
 
-> Easily configure an Emoji Picker for the Portable Text Editor
+> ⚡️ Easily configure an Emoji Picker for the Portable Text Editor
+
+## Quick Start
+
+The `useEmojiPicker` hook handles the state and logic needed to create an emoji picker for the Portable Text Editor. It manages keyword matching, keyboard navigation, and emoji insertion, but is not concerned with the UI, how the picker is rendered, or how it's positioned in the document.
+
+```tsx
+import {matchEmojis, useEmojiPicker} from '@portabletext/plugin-emoji-picker'
+
+function EmojiPicker() {
+  const {keyword, matches, selectedIndex, onNavigateTo, onSelect, onDismiss} =
+    useEmojiPicker({matchEmojis})
+
+  if (keyword.length < 2) {
+    return null
+  }
+
+  return (
+    <div className="emoji-picker">
+      {matches.length === 0 ? (
+        <div>
+          No emojis found for "{keyword}"
+          <button onClick={onDismiss}>Dismiss</button>
+        </div>
+      ) : (
+        <ul>
+          {matches.map((match, index) => (
+            <li
+              key={match.key}
+              onMouseEnter={() => onNavigateTo(index)}
+              onClick={onSelect}
+              className={selectedIndex === index ? 'selected' : ''}
+            >
+              {match.emoji} {match.keyword}
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  )
+}
+```
+
+## How It Works
+
+The emoji picker activates when users type `:` followed by a keyword (e.g., `:smile` or `:joy`).
+
+- **Keyboard shortcuts are built-in**:
+  - `Enter` or `Tab` inserts the selected emoji
+  - `↑` / `↓` navigate through matches
+  - `Esc` dismisses the picker
+- **Mouse interactions are opt-in**: Use `onNavigateTo` and `onSelect` to enable hover and click
+
+## API Reference
+
+### `useEmojiPicker(props)`
+
+**Props:**
+
+- `matchEmojis`: A function that takes a keyword and returns matching emojis
+
+**Returns:**
+
+- `keyword`: The matches keyword, including colons.
+- `matches`: Emoji matches found for the current keyword.
+- `selectedIndex`: Index of the selected match
+- `onNavigateTo(index)`: Navigate to a specific match by index.
+- `onSelect()`: Select the current match.
+- `onDismiss()`: Dismiss the emoji picker.
+
+## Custom Emoji Sets
+
+The `matchEmojis` function is generic and can return any shape of emoji match required for your UI. However, the default implementation returns `EmojiMatch` objects and can be created using `createMatchEmojis`:
+
+```tsx
+import {
+  createMatchEmojis,
+  useEmojiPicker,
+} from '@portabletext/plugin-emoji-picker'
+
+const myMatchEmojis = createMatchEmojis({
+  emojis: {
+    '😂': ['joy', 'laugh'],
+    '😹': ['joy_cat', 'laugh_cat'],
+    '❤️': ['heart', 'love'],
+    '🎉': ['party', 'celebrate'],
+  },
+})
+
+function MyEmojiPicker() {
+  const picker = useEmojiPicker({matchEmojis: myMatchEmojis})
+  // ... render your UI
+}
+```
+
+The default `matchEmojis` export includes a comprehensive set of emojis. You can also implement a completely custom matching function that returns any shape you need for your specific UI requirements.

package/dist/index.cjs

@@ -2049,7 +2049,7 @@ function createKeywordFoundEvent(payload) {
     ...payload
   };
 }
-const colonListenerCallback = ({
+const triggerListenerCallback = ({
   sendBack,
   input
 }) => {
@@ -2072,10 +2072,7 @@ const colonListenerCallback = ({
       actions: [({
         event
       }) => [behaviors.effect(() => {
-        sendBack({
-          ...event,
-          type: "colon inserted"
-        });
+        sendBack(event);
       })]]
     })
   }), input.editor.registerBehavior({
@@ -2084,10 +2081,7 @@ const colonListenerCallback = ({
       actions: [({
         event
       }) => [behaviors.effect(() => {
-        sendBack({
-          ...event,
-          type: "colon inserted"
-        });
+        sendBack(event);
       })]]
     })
   })];
@@ -2145,65 +2139,28 @@ const colonListenerCallback = ({
   };
 }, emojiInsertListener = ({
   sendBack,
-  input,
-  receive
-}) => {
-  let context = input.context;
-  receive((event) => {
-    context = event.context;
-  });
-  const unregisterBehaviors = [input.context.editor.registerBehavior({
-    behavior: behaviors.defineBehavior({
-      on: "custom.insert emoji",
-      actions: [({
-        event
-      }) => [behaviors.effect(() => {
-        sendBack({
-          type: "dismiss"
-        });
-      }), behaviors.raise({
-        type: "delete.text",
-        at: {
-          anchor: event.anchor,
-          focus: event.focus
-        }
-      }), behaviors.raise({
-        type: "insert.text",
-        text: event.emoji
-      })]]
-    })
-  }), input.context.editor.registerBehavior({
-    behavior: behaviors.defineBehavior({
-      on: "insert.text",
-      guard: ({
-        event
-      }) => {
-        if (event.text !== ":")
-          return !1;
-        const anchor = context.keywordAnchor?.blockOffset, focus = context.keywordFocus, match = context.matches[context.selectedIndex];
-        return match && match.type === "exact" && anchor && focus ? {
-          anchor,
-          focus,
-          emoji: match.emoji
-        } : !1;
-      },
-      actions: [(_, {
-        anchor,
-        focus,
-        emoji
-      }) => [behaviors.raise({
-        type: "custom.insert emoji",
-        emoji,
-        anchor,
-        focus
-      })]]
-    })
-  })];
-  return () => {
-    for (const unregister of unregisterBehaviors)
-      unregister();
-  };
-}, submitListenerCallback = ({
+  input
+}) => input.context.editor.registerBehavior({
+  behavior: behaviors.defineBehavior({
+    on: "custom.insert emoji",
+    actions: [({
+      event
+    }) => [behaviors.effect(() => {
+      sendBack({
+        type: "dismiss"
+      });
+    }), behaviors.raise({
+      type: "delete.text",
+      at: {
+        anchor: event.anchor,
+        focus: event.focus
+      }
+    }), behaviors.raise({
+      type: "insert.text",
+      text: event.emoji
+    })]]
+  })
+}), submitListenerCallback = ({
   sendBack,
   input,
   receive
@@ -2250,6 +2207,19 @@ const colonListenerCallback = ({
         });
       })]]
     })
+  }), input.context.editor.registerBehavior({
+    behavior: pluginInputRule.defineInputRuleBehavior({
+      rules: [keywordRule]
+    })
+  }), input.context.editor.registerBehavior({
+    behavior: behaviors.defineBehavior({
+      on: "custom.keyword found",
+      actions: [({
+        event
+      }) => [behaviors.effect(() => {
+        sendBack(event);
+      })]]
+    })
   })];
   return () => {
     for (const unregister of unregisterBehaviors)
@@ -2342,7 +2312,7 @@ const colonListenerCallback = ({
     "emoji insert listener": xstate.fromCallback(emojiInsertListener),
     "submit listener": xstate.fromCallback(submitListenerCallback),
     "arrow listener": xstate.fromCallback(arrowListenerCallback),
-    "colon listener": xstate.fromCallback(colonListenerCallback),
+    "trigger listener": xstate.fromCallback(triggerListenerCallback),
     "escape listener": xstate.fromCallback(escapeListenerCallback),
     "selection listener": xstate.fromCallback(selectionListenerCallback),
     "text change listener": xstate.fromCallback(textChangeListener)
@@ -2352,19 +2322,19 @@ const colonListenerCallback = ({
       keyword: ({
         context,
         event
-      }) => event.type !== "colon inserted" && event.type !== "custom.keyword found" ? context.keyword : event.keyword
+      }) => event.type !== "custom.trigger found" && event.type !== "custom.partial keyword found" && event.type !== "custom.keyword found" ? context.keyword : event.keyword
     }),
     "set keyword anchor": xstate.assign({
       keywordAnchor: ({
         context,
         event
-      }) => event.type !== "colon inserted" && event.type !== "custom.keyword found" ? context.keywordAnchor : event.keywordAnchor
+      }) => event.type !== "custom.trigger found" && event.type !== "custom.partial keyword found" && event.type !== "custom.keyword found" ? context.keywordAnchor : event.keywordAnchor
     }),
     "set keyword focus": xstate.assign({
       keywordFocus: ({
         context,
         event
-      }) => event.type !== "colon inserted" && event.type !== "custom.keyword found" ? context.keywordFocus : event.keywordFocus
+      }) => event.type !== "custom.trigger found" && event.type !== "custom.partial keyword found" && event.type !== "custom.keyword found" ? context.keywordFocus : event.keywordFocus
     }),
     "update keyword focus": xstate.assign({
       keywordFocus: ({
@@ -2440,10 +2410,11 @@ const colonListenerCallback = ({
       context
     })),
     "insert selected match": ({
-      context
+      context,
+      event
     }) => {
       const match = context.matches[context.selectedIndex];
-      !match || !context.keywordAnchor || !context.keywordFocus || context.editor.send({
+      !match || !context.keywordAnchor || !context.keywordFocus || event.type === "custom.keyword found" && match.type !== "exact" || context.editor.send({
         type: "custom.insert emoji",
         emoji: match.emoji,
         anchor: context.keywordAnchor.blockOffset,
@@ -2536,7 +2507,7 @@ const colonListenerCallback = ({
     idle: {
       entry: ["reset"],
       invoke: {
-        src: "colon listener",
+        src: "trigger listener",
         input: ({
           context
         }) => ({
@@ -2544,12 +2515,18 @@ const colonListenerCallback = ({
         })
       },
       on: {
-        "colon inserted": {
+        "custom.trigger found": {
+          target: "searching",
+          actions: ["set keyword anchor", "set keyword focus", "init keyword"]
+        },
+        "custom.partial keyword found": {
           target: "searching",
           actions: ["set keyword anchor", "set keyword focus", "init keyword"]
         },
         "custom.keyword found": {
-          actions: ["set keyword anchor", "set keyword focus", "init keyword", "update matches", "insert selected match"]
+          actions: ["set keyword anchor", "set keyword focus", "init keyword", "update matches", "insert selected match"],
+          target: "idle",
+          reenter: !0
         }
       }
     },
@@ -2585,6 +2562,9 @@ const colonListenerCallback = ({
         })
       }],
       on: {
+        "custom.keyword found": {
+          actions: ["set keyword anchor", "set keyword focus", "init keyword", "update matches", "insert selected match"]
+        },
         "insert.text": [{
           guard: "unexpected text insertion",
           target: "idle"
@@ -2604,7 +2584,7 @@ const colonListenerCallback = ({
           guard: "selection moved unexpectedly",
           target: "idle"
         }, {
-          actions: ["update keyword", "update matches", "reset selected index", "update emoji insert listener context", "update submit listener context"]
+          actions: ["update keyword", "update matches", "reset selected index", "update submit listener context"]
         }]
       },
       always: [{
@@ -2635,13 +2615,13 @@ const colonListenerCallback = ({
           }],
           on: {
             "navigate down": {
-              actions: ["increment selected index", "update emoji insert listener context", "update submit listener context"]
+              actions: ["increment selected index", "update submit listener context"]
             },
             "navigate up": {
-              actions: ["decrement selected index", "update emoji insert listener context", "update submit listener context"]
+              actions: ["decrement selected index", "update submit listener context"]
             },
             "navigate to": {
-              actions: ["set selected index", "update emoji insert listener context", "update submit listener context"]
+              actions: ["set selected index", "update submit listener context"]
             },
             "insert selected match": {
               actions: ["insert selected match"]