@portabletext/plugin-emoji-picker 0.0.15

package/dist/index.d.cts

@@ -0,0 +1,209 @@
+/**
+ * Proposed, but not required, function to create a `MatchEmojis` function.
+ *
+ * @example
+ * ```ts
+ * const matchEmojis = createMatchEmojis({
+ *   emojis: {
+ *     '😂': ['joy'],
+ *     '😹': ['joy_cat'],
+ *   },
+ * })
+ * ```
+ *
+ * @beta
+ */
+export declare function createMatchEmojis(config: {
+  emojis: Record<string, ReadonlyArray<string>>
+}): MatchEmojis
+
+/**
+ * Proposed, but not required type, to represent an emoji match.
+ *
+ * @example
+ * ```tsx
+ * {
+ *   type: 'exact',
+ *   key: '😂-joy',
+ *   emoji: '😂',
+ *   keyword: 'joy',
+ * }
+ * ```
+ * @example
+ * ```tsx
+ * {
+ *   type: 'partial',
+ *   key: '😹-joy-_cat',
+ *   emoji: '😹',
+ *   keyword: 'joy',
+ *   startSlice: '',
+ *   endSlice: '_cat',
+ * }
+ * ```
+ *
+ * @beta
+ */
+export declare type EmojiMatch =
+  | {
+      type: 'exact'
+      key: string
+      emoji: string
+      keyword: string
+    }
+  | {
+      type: 'partial'
+      key: string
+      emoji: string
+      keyword: string
+      startSlice: string
+      endSlice: string
+    }
+
+/**
+ * @beta
+ */
+export declare type EmojiPicker<TEmojiMatch = EmojiMatch> = {
+  /**
+   * The matched keyword, including colons.
+   *
+   * Can be used to display the keyword in the UI or conditionally render the
+   * list of matches.
+   *
+   * @example
+   * ```tsx
+   * if (keyword.length < 2) {
+   *   return null
+   * }
+   * ```
+   */
+  keyword: string
+  /**
+   * Emoji matches found for the current keyword.
+   *
+   * Can be used to display the matches in a list.
+   */
+  matches: ReadonlyArray<TEmojiMatch>
+  /**
+   * The index of the selected match.
+   *
+   * Can be used to highlight the selected match in the list.
+   *
+   * @example
+   * ```tsx
+   * <EmojiListItem
+   *   key={match.key}
+   *   match={match}
+   *   selected={selectedIndex === index}
+   * />
+   * ```
+   */
+  selectedIndex: number
+  /**
+   * Navigate to a specific match by index.
+   *
+   * Can be used to control the `selectedIndex`. For example, using
+   * `onMouseEnter`.
+   *
+   * @example
+   * ```tsx
+   * <EmojiListItem
+   *   key={match.key}
+   *   match={match}
+   *   selected={selectedIndex === index}
+   *   onMouseEnter={() => {onNavigateTo(index)}}
+   * />
+   * ```
+   */
+  onNavigateTo: (index: number) => void
+  /**
+   * Select the current match.
+   *
+   * Can be used to insert the currently selected match.
+   *
+   *
+   * @example
+   * ```tsx
+   * <EmojiListItem
+   *   key={match.key}
+   *   match={match}
+   *   selected={selectedIndex === index}
+   *   onMouseEnter={() => {onNavigateTo(index)}}
+   *   onSelect={() => {onSelect()}}
+   * />
+   * ```
+   *
+   * Note: The currently selected match is automatically inserted on Enter or
+   * Tab.
+   */
+  onSelect: () => void
+  /**
+   * Dismiss the emoji picker. Can be used to let the user dismiss the picker
+   * by clicking a button.
+   *
+   * @example
+   * ```tsx
+   * {matches.length === 0 ? (
+   *   <Button onPress={onDismiss}>Dismiss</Button>
+   * ) : <EmojiListBox {...props} />}
+   * ```
+   *
+   * Note: The emoji picker is automatically dismissed on Escape.
+   */
+  onDismiss: () => void
+}
+
+/**
+ * @beta
+ */
+export declare type EmojiPickerProps<TEmojiMatch = EmojiMatch> = {
+  matchEmojis: MatchEmojis<TEmojiMatch>
+}
+
+/**
+ * A function that returns an array of emoji matches for a given keyword.
+ *
+ * @beta
+ */
+export declare type MatchEmojis<TEmojiMatch = EmojiMatch> = (query: {
+  keyword: string
+}) => ReadonlyArray<TEmojiMatch>
+
+/**
+ * Proposed, but not required, default implementation of `MatchEmojis`.
+ *
+ * @beta
+ */
+export declare const matchEmojis: MatchEmojis
+
+/**
+ * Handles the state and logic needed to create an emoji picker.
+ *
+ * The `matchEmojis` function is generic and can return any shape of emoji
+ * match required for the emoji picker.
+ *
+ * However, the default implementation of `matchEmojis` returns an array of
+ * `EmojiMatch` objects and can be created using the `createMatchEmojis`
+ * function.
+ *
+ * @example
+ *
+ * ```tsx
+ * const matchEmojis = createMatchEmojis({emojis: {
+ *   '😂': ['joy'],
+ *   '😹': ['joy_cat'],
+ * }})
+ *
+ * const {keyword, matches, selectedIndex, onDismiss, onNavigateTo, onSelect} =
+ *   useEmojiPicker({matchEmojis})
+ * ```
+ *
+ *  Note: This hook is not concerned with the UI, how the emoji picker is
+ * rendered or positioned in the document.
+ *
+ * @beta
+ */
+export declare function useEmojiPicker<TEmojiMatch = EmojiMatch>(
+  props: EmojiPickerProps<TEmojiMatch>,
+): EmojiPicker<TEmojiMatch>
+
+export {}

package/dist/index.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Proposed, but not required, function to create a `MatchEmojis` function.
+ *
+ * @example
+ * ```ts
+ * const matchEmojis = createMatchEmojis({
+ *   emojis: {
+ *     '😂': ['joy'],
+ *     '😹': ['joy_cat'],
+ *   },
+ * })
+ * ```
+ *
+ * @beta
+ */
+export declare function createMatchEmojis(config: {
+  emojis: Record<string, ReadonlyArray<string>>
+}): MatchEmojis
+
+/**
+ * Proposed, but not required type, to represent an emoji match.
+ *
+ * @example
+ * ```tsx
+ * {
+ *   type: 'exact',
+ *   key: '😂-joy',
+ *   emoji: '😂',
+ *   keyword: 'joy',
+ * }
+ * ```
+ * @example
+ * ```tsx
+ * {
+ *   type: 'partial',
+ *   key: '😹-joy-_cat',
+ *   emoji: '😹',
+ *   keyword: 'joy',
+ *   startSlice: '',
+ *   endSlice: '_cat',
+ * }
+ * ```
+ *
+ * @beta
+ */
+export declare type EmojiMatch =
+  | {
+      type: 'exact'
+      key: string
+      emoji: string
+      keyword: string
+    }
+  | {
+      type: 'partial'
+      key: string
+      emoji: string
+      keyword: string
+      startSlice: string
+      endSlice: string
+    }
+
+/**
+ * @beta
+ */
+export declare type EmojiPicker<TEmojiMatch = EmojiMatch> = {
+  /**
+   * The matched keyword, including colons.
+   *
+   * Can be used to display the keyword in the UI or conditionally render the
+   * list of matches.
+   *
+   * @example
+   * ```tsx
+   * if (keyword.length < 2) {
+   *   return null
+   * }
+   * ```
+   */
+  keyword: string
+  /**
+   * Emoji matches found for the current keyword.
+   *
+   * Can be used to display the matches in a list.
+   */
+  matches: ReadonlyArray<TEmojiMatch>
+  /**
+   * The index of the selected match.
+   *
+   * Can be used to highlight the selected match in the list.
+   *
+   * @example
+   * ```tsx
+   * <EmojiListItem
+   *   key={match.key}
+   *   match={match}
+   *   selected={selectedIndex === index}
+   * />
+   * ```
+   */
+  selectedIndex: number
+  /**
+   * Navigate to a specific match by index.
+   *
+   * Can be used to control the `selectedIndex`. For example, using
+   * `onMouseEnter`.
+   *
+   * @example
+   * ```tsx
+   * <EmojiListItem
+   *   key={match.key}
+   *   match={match}
+   *   selected={selectedIndex === index}
+   *   onMouseEnter={() => {onNavigateTo(index)}}
+   * />
+   * ```
+   */
+  onNavigateTo: (index: number) => void
+  /**
+   * Select the current match.
+   *
+   * Can be used to insert the currently selected match.
+   *
+   *
+   * @example
+   * ```tsx
+   * <EmojiListItem
+   *   key={match.key}
+   *   match={match}
+   *   selected={selectedIndex === index}
+   *   onMouseEnter={() => {onNavigateTo(index)}}
+   *   onSelect={() => {onSelect()}}
+   * />
+   * ```
+   *
+   * Note: The currently selected match is automatically inserted on Enter or
+   * Tab.
+   */
+  onSelect: () => void
+  /**
+   * Dismiss the emoji picker. Can be used to let the user dismiss the picker
+   * by clicking a button.
+   *
+   * @example
+   * ```tsx
+   * {matches.length === 0 ? (
+   *   <Button onPress={onDismiss}>Dismiss</Button>
+   * ) : <EmojiListBox {...props} />}
+   * ```
+   *
+   * Note: The emoji picker is automatically dismissed on Escape.
+   */
+  onDismiss: () => void
+}
+
+/**
+ * @beta
+ */
+export declare type EmojiPickerProps<TEmojiMatch = EmojiMatch> = {
+  matchEmojis: MatchEmojis<TEmojiMatch>
+}
+
+/**
+ * A function that returns an array of emoji matches for a given keyword.
+ *
+ * @beta
+ */
+export declare type MatchEmojis<TEmojiMatch = EmojiMatch> = (query: {
+  keyword: string
+}) => ReadonlyArray<TEmojiMatch>
+
+/**
+ * Proposed, but not required, default implementation of `MatchEmojis`.
+ *
+ * @beta
+ */
+export declare const matchEmojis: MatchEmojis
+
+/**
+ * Handles the state and logic needed to create an emoji picker.
+ *
+ * The `matchEmojis` function is generic and can return any shape of emoji
+ * match required for the emoji picker.
+ *
+ * However, the default implementation of `matchEmojis` returns an array of
+ * `EmojiMatch` objects and can be created using the `createMatchEmojis`
+ * function.
+ *
+ * @example
+ *
+ * ```tsx
+ * const matchEmojis = createMatchEmojis({emojis: {
+ *   '😂': ['joy'],
+ *   '😹': ['joy_cat'],
+ * }})
+ *
+ * const {keyword, matches, selectedIndex, onDismiss, onNavigateTo, onSelect} =
+ *   useEmojiPicker({matchEmojis})
+ * ```
+ *
+ *  Note: This hook is not concerned with the UI, how the emoji picker is
+ * rendered or positioned in the document.
+ *
+ * @beta
+ */
+export declare function useEmojiPicker<TEmojiMatch = EmojiMatch>(
+  props: EmojiPickerProps<TEmojiMatch>,
+): EmojiPicker<TEmojiMatch>
+
+export {}