@meta-1/editor 0.0.29 → 1.0.0

package/src/components/tiptap-ui/mention-dropdown-menu/mention-dropdown-menu.tsx

@@ -0,0 +1,212 @@
+"use client"
+
+import { useEffect, useMemo, useRef } from "react"
+import type { Editor, Range } from "@tiptap/react"
+
+// --- Lib ---
+import { getElementOverflowPosition } from "../../../lib/tiptap-collab-utils"
+
+// --- Tiptap UI ---
+import type {
+  SuggestionItem,
+  SuggestionMenuProps,
+  SuggestionMenuRenderProps,
+} from "../../tiptap-ui-utils/suggestion-menu"
+import { SuggestionMenu } from "../../tiptap-ui-utils/suggestion-menu"
+
+// --- UI Primitives ---
+import {
+  Avatar,
+  AvatarImage,
+  AvatarFallback,
+} from "../../tiptap-ui-primitive/avatar"
+import { Button, ButtonGroup } from "../../tiptap-ui-primitive/button"
+import { Card, CardBody } from "../../tiptap-ui-primitive/card"
+
+interface User {
+  id: number
+  name: string
+  position: string
+  avatarUrl: string
+}
+
+type MentionDropdownMenuProps = Omit<SuggestionMenuProps, "items" | "children">
+
+interface MentionItemProps {
+  item: SuggestionItem<User>
+  isSelected: boolean
+  onSelect: () => void
+}
+
+const fetchUsers = async (query: string): Promise<User[]> => {
+  const employeeData = [
+    ["Emily Johnson", "Marketing Manager"],
+    ["Michael Thompson", "Sales Manager"],
+    ["Sophia Lee", "Product Designer"],
+    ["William Davis", "IT Project Manager"],
+    ["Olivia Wilson", "HR Specialist"],
+    ["Daniel Taylor", "Financial Controller"],
+    ["Isabella Anderson", "Graphic Designer"],
+    ["Jacob Martinez", "Sales Representative"],
+    ["Ava Hernandez", "Marketing Assistant"],
+    ["Alexander Diaz", "IT Support"],
+    ["Emma Ramirez", "HR Specialist"],
+    ["Ethan Flores", "Product Manager"],
+    ["Mia Morales", "Graphic Designer"],
+    ["Noah Reyes", "Sales Manager"],
+    ["Isabella Castillo", "Marketing Manager"],
+    ["Liam Gutierrez", "IT Project Manager"],
+    ["Avery Jimenez", "HR Specialist"],
+    ["Lucas Vargas", "Product Designer"],
+    ["Chloe Rojas", "Graphic Designer"],
+    ["Kai Zhang", "Sales Representative"],
+  ] as const
+
+  const userData = {
+    users: employeeData.map(([name, position], index) => {
+      const id = index + 1
+      const avatarNumber = id < 10 ? `0${id}` : `${id}`
+
+      return {
+        id,
+        name,
+        position,
+        avatarUrl: `/avatars/memoji_${avatarNumber}.png`,
+      }
+    }),
+  }
+
+  if (!query) return userData.users
+
+  return userData.users.filter(
+    (user) =>
+      user.name.toLowerCase().includes(query.toLowerCase()) ||
+      user.position.toLowerCase().includes(query.toLowerCase())
+  )
+}
+
+export const MentionDropdownMenu = (props: MentionDropdownMenuProps) => {
+  const handleItemSelect = (props: {
+    editor: Editor
+    range: Range
+    context?: User
+  }) => {
+    if (!props.editor || !props.range || !props.context) return
+
+    props.editor
+      .chain()
+      .focus()
+      .insertContentAt(props.range, [
+        {
+          type: "mention",
+          attrs: {
+            id: props.context.id.toString(),
+            label: props.context.name,
+          },
+        },
+        {
+          type: "text",
+          text: " ",
+        },
+      ])
+      .run()
+  }
+
+  const getSuggestionItems = async (props: { query: string }) => {
+    const users = await fetchUsers(props.query)
+
+    return users.map((user) => ({
+      title: user.name,
+      subtext: user.name,
+      context: user,
+      onSelect: handleItemSelect,
+    }))
+  }
+
+  return (
+    <SuggestionMenu
+      char="@"
+      pluginKey="mentionDropdownMenu"
+      decorationClass="tiptap-mention-decoration"
+      selector="tiptap-mention-dropdown-menu"
+      items={getSuggestionItems}
+      {...props}
+    >
+      {(props) => <MentionList {...props} />}
+    </SuggestionMenu>
+  )
+}
+
+const MentionItem = ({ item, isSelected, onSelect }: MentionItemProps) => {
+  const itemRef = useRef<HTMLButtonElement>(null)
+
+  useEffect(() => {
+    const menuElement = document.querySelector(
+      '[data-selector="tiptap-mention-dropdown-menu"]'
+    ) as HTMLElement
+    if (!itemRef.current || !isSelected || !menuElement) return
+
+    const overflow = getElementOverflowPosition(itemRef.current, menuElement)
+    if (overflow === "top") {
+      itemRef.current.scrollIntoView(true)
+    } else if (overflow === "bottom") {
+      itemRef.current.scrollIntoView(false)
+    }
+  }, [isSelected])
+
+  return (
+    <Button
+      ref={itemRef}
+      data-style="ghost"
+      data-active-state={isSelected ? "on" : "off"}
+      onClick={onSelect}
+      data-user-id={item.context?.id}
+    >
+      <Avatar>
+        <AvatarImage src={item.context?.avatarUrl} alt={item.title} />
+        <AvatarFallback>{item.title[0]?.toUpperCase()}</AvatarFallback>
+      </Avatar>
+
+      <span className="tiptap-button-text">{item.title}</span>
+    </Button>
+  )
+}
+
+const MentionList = ({
+  items,
+  selectedIndex,
+  onSelect,
+}: SuggestionMenuRenderProps<User>) => {
+  const renderedItems = useMemo(() => {
+    const rendered: React.ReactElement[] = []
+
+    items.forEach((item, index) => {
+      rendered.push(
+        <MentionItem
+          key={item.context?.id || item.title}
+          item={item}
+          isSelected={index === selectedIndex}
+          onSelect={() => onSelect(item)}
+        />
+      )
+    })
+
+    return rendered
+  }, [items, selectedIndex, onSelect])
+
+  if (!renderedItems.length) {
+    return null
+  }
+
+  return (
+    <Card
+      style={{
+        maxHeight: "var(--suggestion-menu-max-height)",
+      }}
+    >
+      <CardBody>
+        <ButtonGroup>{renderedItems}</ButtonGroup>
+      </CardBody>
+    </Card>
+  )
+}

package/src/components/tiptap-ui/mention-trigger-button/index.tsx

@@ -0,0 +1,2 @@
+export * from "./mention-trigger-button"
+export * from "./use-mention-trigger"

package/src/components/tiptap-ui/mention-trigger-button/mention-trigger-button.tsx

@@ -0,0 +1,122 @@
+"use client"
+
+import { forwardRef, useCallback } from "react"
+
+// --- Lib ---
+import { parseShortcutKeys } from "../../../lib/tiptap-utils"
+
+// --- Hooks ---
+import { useTiptapEditor } from "../../../hooks/use-tiptap-editor"
+
+// --- Tiptap UI ---
+import type { UseMentionTriggerConfig } from "./"
+import {
+  MENTION_TRIGGER_SHORTCUT_KEY,
+  useMentionTrigger,
+} from "./"
+
+// --- UI Primitives ---
+import type { ButtonProps } from "../../tiptap-ui-primitive/button"
+import { Button } from "../../tiptap-ui-primitive/button"
+import { Badge } from "../../tiptap-ui-primitive/badge"
+
+export interface MentionTriggerButtonProps
+  extends Omit<ButtonProps, "type">,
+    UseMentionTriggerConfig {
+  /**
+   * Optional text to display alongside the icon.
+   */
+  text?: string
+  /**
+   * Optional show shortcut keys in the button.
+   * @default false
+   */
+  showShortcut?: boolean
+}
+
+export function MentionShortcutBadge({
+  shortcutKeys = MENTION_TRIGGER_SHORTCUT_KEY,
+}: {
+  shortcutKeys?: string
+}) {
+  return <Badge>{parseShortcutKeys({ shortcutKeys })}</Badge>
+}
+
+/**
+ * Button component for inserting mention triggers in a Tiptap editor.
+ *
+ * For custom button implementations, use the `useMention` hook instead.
+ */
+export const MentionTriggerButton = forwardRef<
+  HTMLButtonElement,
+  MentionTriggerButtonProps
+>(
+  (
+    {
+      editor: providedEditor,
+      node,
+      nodePos,
+      text,
+      trigger = "@",
+      hideWhenUnavailable = false,
+      onTriggered,
+      showShortcut = false,
+      onClick,
+      children,
+      ...buttonProps
+    },
+    ref
+  ) => {
+    const { editor } = useTiptapEditor(providedEditor)
+    const { isVisible, canInsert, handleMention, label, shortcutKeys, Icon } =
+      useMentionTrigger({
+        editor,
+        node,
+        nodePos,
+        trigger,
+        hideWhenUnavailable,
+        onTriggered,
+      })
+
+    const handleClick = useCallback(
+      (event: React.MouseEvent<HTMLButtonElement>) => {
+        onClick?.(event)
+        if (event.defaultPrevented) return
+        handleMention()
+      },
+      [handleMention, onClick]
+    )
+
+    if (!isVisible) {
+      return null
+    }
+
+    return (
+      <Button
+        type="button"
+        data-style="ghost"
+        role="button"
+        tabIndex={-1}
+        disabled={!canInsert}
+        data-disabled={!canInsert}
+        aria-label={label}
+        tooltip={label}
+        onClick={handleClick}
+        {...buttonProps}
+        ref={ref}
+      >
+        {children ?? (
+          <>
+            <Icon className="tiptap-button-icon" />
+            {text && <span className="tiptap-button-text">{text}</span>}
+            {showShortcut && (
+              <MentionShortcutBadge shortcutKeys={shortcutKeys} />
+            )}
+          </>
+        )}
+      </Button>
+    )
+  }
+)
+
+MentionTriggerButton.displayName = "MentionTriggerButton"

package/src/components/tiptap-ui/mention-trigger-button/use-mention-trigger.ts

@@ -0,0 +1,339 @@
+"use client"
+
+import { useCallback, useEffect, useState } from "react"
+import { useHotkeys } from "react-hotkeys-hook"
+import { type Editor } from "@tiptap/react"
+import type { Node } from "@tiptap/pm/model"
+
+// --- Hooks ---
+import { useTiptapEditor } from "../../../hooks/use-tiptap-editor"
+import { useIsBreakpoint } from "../../../hooks/use-is-breakpoint"
+
+// --- Lib ---
+import {
+  findNodePosition,
+  isNodeTypeSelected,
+  isValidPosition,
+} from "../../../lib/tiptap-utils"
+
+// --- Icons ---
+import { AtSignIcon } from "../../tiptap-icons/at-sign-icon"
+
+export const MENTION_TRIGGER_SHORTCUT_KEY = "mod+shift+2"
+
+/**
+ * Configuration for the mention functionality
+ */
+export interface UseMentionTriggerConfig {
+  /**
+   * The Tiptap editor instance.
+   */
+  editor?: Editor | null
+  /**
+   * The node to apply trigger to
+   */
+  node?: Node | null
+  /**
+   * The position of the node in the document
+   */
+  nodePos?: number | null
+  /**
+   * The trigger text to insert
+   * @default "@"
+   */
+  trigger?: string
+  /**
+   * Whether the button should hide when insertion is not available.
+   * @default false
+   */
+  hideWhenUnavailable?: boolean
+  /**
+   * Callback function called after a successful trigger insertion.
+   */
+  onTriggered?: (trigger: string) => void
+}
+
+/**
+ * Checks if a mention can be inserted in the current editor state
+ */
+export function canInsertMention(
+  editor: Editor | null,
+  node?: Node | null,
+  nodePos?: number | null
+): boolean {
+  if (!editor || !editor.isEditable) return false
+  if (isNodeTypeSelected(editor, ["image"])) return false
+
+  if (node || isValidPosition(nodePos)) {
+    if (isValidPosition(nodePos) && nodePos! >= 0) return true
+
+    if (node) {
+      const foundPos = findNodePosition({ editor, node })
+      return foundPos !== null
+    }
+  }
+
+  return true
+}
+
+/**
+ * Inserts a trigger in a block node at a specified position or after the current selection
+ */
+function insertTriggerInBlockNode(
+  editor: Editor,
+  trigger: string,
+  node?: Node | null,
+  nodePos?: number | null
+): boolean {
+  if ((node !== undefined && node !== null) || isValidPosition(nodePos)) {
+    const foundPos = findNodePosition({
+      editor,
+      node: node || undefined,
+      nodePos: nodePos || undefined,
+    })
+
+    if (!foundPos) {
+      return false
+    }
+
+    const isEmpty =
+      foundPos.node.type.name === "paragraph" &&
+      foundPos.node.content.size === 0
+    const insertPos = isEmpty
+      ? foundPos.pos
+      : foundPos.pos + foundPos.node.nodeSize
+
+    const triggerLength = trigger.length + 1 // +1 for the space after the trigger
+    const focusPos = isEmpty
+      ? foundPos.pos + triggerLength
+      : foundPos.pos + foundPos.node.nodeSize + triggerLength
+
+    return editor
+      .chain()
+      .insertContentAt(isEmpty ? foundPos.pos : insertPos, {
+        type: "paragraph",
+        content: [{ type: "text", text: trigger }],
+      })
+      .focus(focusPos)
+      .run()
+  }
+
+  const { $from } = editor.state.selection
+
+  return editor
+    .chain()
+    .insertContentAt($from.after(), {
+      type: "paragraph",
+      content: [{ type: "text", text: trigger }],
+    })
+    .focus()
+    .run()
+}
+
+/**
+ * Inserts a trigger in a text node at the current selection
+ */
+function insertTriggerInTextNode(
+  editor: Editor,
+  trigger: string,
+  node?: Node | null,
+  nodePos?: number | null
+): boolean {
+  if ((node !== undefined && node !== null) || isValidPosition(nodePos)) {
+    const foundPos = findNodePosition({
+      editor,
+      node: node || undefined,
+      nodePos: nodePos || undefined,
+    })
+
+    if (!foundPos) {
+      return false
+    }
+
+    const isEmpty =
+      foundPos.node.type.name === "paragraph" &&
+      foundPos.node.content.size === 0
+    const insertPos = isEmpty
+      ? foundPos.pos
+      : foundPos.pos + foundPos.node.nodeSize
+
+    editor.view.dispatch(
+      editor.view.state.tr
+        .scrollIntoView()
+        .insertText(trigger, insertPos, insertPos)
+    )
+
+    const triggerLength = trigger.length + 1 // +1 for the space after the trigger
+    const focusPos = isEmpty
+      ? foundPos.pos + triggerLength
+      : foundPos.pos + foundPos.node.nodeSize + triggerLength
+    editor.commands.focus(focusPos)
+
+    return true
+  }
+
+  const { $from } = editor.state.selection
+  const currentNode = $from.node()
+  const hasContentBefore =
+    $from.parentOffset > 0 &&
+    currentNode.textContent[$from.parentOffset - 1] !== " "
+
+  return editor
+    .chain()
+    .insertContent({
+      type: "text",
+      text: hasContentBefore ? ` ${trigger}` : trigger,
+    })
+    .focus()
+    .run()
+}
+
+/**
+ * Adds a mention trigger at the current selection or specified node position
+ */
+export function addMentionTrigger(
+  editor: Editor | null,
+  trigger: string = "@",
+  node?: Node | null,
+  nodePos?: number | null
+): boolean {
+  if (!editor || !editor.isEditable) return false
+  if (!canInsertMention(editor, node, nodePos)) return false
+
+  try {
+    const { $from } = editor.state.selection
+    const currentNode = $from.node()
+    const isBlockNode = currentNode.isBlock && !currentNode.isTextblock
+
+    if (isBlockNode) {
+      return insertTriggerInBlockNode(editor, trigger, node, nodePos)
+    }
+
+    return insertTriggerInTextNode(editor, trigger, node, nodePos)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Determines if the mention button should be shown
+ */
+export function shouldShowButton(props: {
+  editor: Editor | null
+  hideWhenUnavailable: boolean
+  node?: Node | null
+  nodePos?: number | null
+}): boolean {
+  const { editor, hideWhenUnavailable, node, nodePos } = props
+
+  if (!editor || !editor.isEditable) return false
+
+  if (hideWhenUnavailable && !editor.isActive("code")) {
+    return canInsertMention(editor, node, nodePos)
+  }
+
+  return true
+}
+
+/**
+ * Custom hook that provides mention functionality for Tiptap editor
+ *
+ * @example
+ * ```tsx
+ * // Simple usage - no params needed
+ * function MySimpleMentionButton() {
+ *   const { isVisible, handleMention } = useMentionTrigger()
+ *
+ *   if (!isVisible) return null
+ *
+ *   return <button onClick={handleMention}>Add Mention</button>
+ * }
+ *
+ * // Advanced usage with configuration
+ * function MyAdvancedMentionButton() {
+ *   const { isVisible, handleMention, label } = useMentionTrigger({
+ *     editor: myEditor,
+ *     trigger: "@",
+ *     hideWhenUnavailable: true,
+ *     onTriggered: (trigger) => console.log('Inserted:', trigger)
+ *   })
+ *
+ *   if (!isVisible) return null
+ *
+ *   return (
+ *     <MyButton
+ *       onClick={handleMention}
+ *       aria-label={label}
+ *     >
+ *       Add Mention
+ *     </MyButton>
+ *   )
+ * }
+ * ```
+ */
+export function useMentionTrigger(config?: UseMentionTriggerConfig) {
+  const {
+    editor: providedEditor,
+    node,
+    nodePos,
+    trigger = "@",
+    hideWhenUnavailable = false,
+    onTriggered,
+  } = config || {}
+
+  const { editor } = useTiptapEditor(providedEditor)
+  const isMobile = useIsBreakpoint()
+  const [isVisible, setIsVisible] = useState<boolean>(true)
+  const canInsert = canInsertMention(editor, node, nodePos)
+
+  useEffect(() => {
+    if (!editor) return
+
+    const handleSelectionUpdate = () => {
+      setIsVisible(
+        shouldShowButton({ editor, hideWhenUnavailable, node, nodePos })
+      )
+    }
+
+    handleSelectionUpdate()
+
+    editor.on("selectionUpdate", handleSelectionUpdate)
+
+    return () => {
+      editor.off("selectionUpdate", handleSelectionUpdate)
+    }
+  }, [editor, hideWhenUnavailable, node, nodePos])
+
+  const handleMention = useCallback(() => {
+    if (!editor) return false
+
+    const success = addMentionTrigger(editor, trigger, node, nodePos)
+    if (success) {
+      onTriggered?.(trigger)
+    }
+    return success
+  }, [editor, trigger, node, nodePos, onTriggered])
+
+  useHotkeys(
+    MENTION_TRIGGER_SHORTCUT_KEY,
+    (event) => {
+      event.preventDefault()
+      handleMention()
+    },
+    {
+      enabled: isVisible && canInsert,
+      enableOnContentEditable: !isMobile,
+      enableOnFormTags: true,
+    }
+  )
+
+  return {
+    isVisible,
+    handleMention,
+    canInsert,
+    label: "Add mention",
+    shortcutKeys: MENTION_TRIGGER_SHORTCUT_KEY,
+    trigger,
+    Icon: AtSignIcon,
+  }
+}

package/src/components/tiptap-ui/move-node-button/index.tsx

@@ -0,0 +1,2 @@
+export * from "./move-node-button"
+export * from "./use-move-node"