@meta-1/editor 0.0.29 → 1.0.0

package/src/components/tiptap-ui-primitive/tooltip/tooltip.tsx

@@ -0,0 +1,237 @@
+"use client"
+
+import {
+  cloneElement,
+  createContext,
+  forwardRef,
+  isValidElement,
+  useContext,
+  useMemo,
+  useState,
+  version,
+} from "react"
+import {
+  useFloating,
+  autoUpdate,
+  offset,
+  flip,
+  shift,
+  useHover,
+  useFocus,
+  useDismiss,
+  useRole,
+  useInteractions,
+  useMergeRefs,
+  FloatingPortal,
+  type Placement,
+  type UseFloatingReturn,
+  type ReferenceType,
+  FloatingDelayGroup,
+} from "@floating-ui/react"
+import "./tooltip.css"
+
+interface TooltipProviderProps {
+  children: React.ReactNode
+  initialOpen?: boolean
+  placement?: Placement
+  open?: boolean
+  onOpenChange?: (open: boolean) => void
+  delay?: number
+  closeDelay?: number
+  timeout?: number
+  useDelayGroup?: boolean
+}
+
+interface TooltipTriggerProps
+  extends Omit<React.HTMLProps<HTMLElement>, "ref"> {
+  asChild?: boolean
+  children: React.ReactNode
+}
+
+interface TooltipContentProps
+  extends Omit<React.HTMLProps<HTMLDivElement>, "ref"> {
+  children?: React.ReactNode
+  portal?: boolean
+  portalProps?: Omit<React.ComponentProps<typeof FloatingPortal>, "children">
+}
+
+interface TooltipContextValue extends UseFloatingReturn<ReferenceType> {
+  open: boolean
+  setOpen: (open: boolean) => void
+  getReferenceProps: (
+    userProps?: React.HTMLProps<HTMLElement>
+  ) => Record<string, unknown>
+  getFloatingProps: (
+    userProps?: React.HTMLProps<HTMLDivElement>
+  ) => Record<string, unknown>
+}
+
+function useTooltip({
+  initialOpen = false,
+  placement = "top",
+  open: controlledOpen,
+  onOpenChange: setControlledOpen,
+  delay = 600,
+  closeDelay = 0,
+}: Omit<TooltipProviderProps, "children"> = {}) {
+  const [uncontrolledOpen, setUncontrolledOpen] = useState<boolean>(initialOpen)
+
+  const open = controlledOpen ?? uncontrolledOpen
+  const setOpen = setControlledOpen ?? setUncontrolledOpen
+
+  const data = useFloating({
+    placement,
+    open,
+    onOpenChange: setOpen,
+    whileElementsMounted: autoUpdate,
+    middleware: [
+      offset(4),
+      flip({
+        crossAxis: placement.includes("-"),
+        fallbackAxisSideDirection: "start",
+        padding: 4,
+      }),
+      shift({ padding: 4 }),
+    ],
+  })
+
+  const context = data.context
+
+  const hover = useHover(context, {
+    mouseOnly: true,
+    move: false,
+    restMs: delay,
+    enabled: controlledOpen == null,
+    delay: {
+      close: closeDelay,
+    },
+  })
+  const focus = useFocus(context, {
+    enabled: controlledOpen == null,
+  })
+  const dismiss = useDismiss(context)
+  const role = useRole(context, { role: "tooltip" })
+
+  const interactions = useInteractions([hover, focus, dismiss, role])
+
+  return useMemo(
+    () => ({
+      open,
+      setOpen,
+      ...interactions,
+      ...data,
+    }),
+    [open, setOpen, interactions, data]
+  )
+}
+
+const TooltipContext = createContext<TooltipContextValue | null>(null)
+
+function useTooltipContext() {
+  const context = useContext(TooltipContext)
+
+  if (context == null) {
+    throw new Error("Tooltip components must be wrapped in <TooltipProvider />")
+  }
+
+  return context
+}
+
+export function Tooltip({ children, ...props }: TooltipProviderProps) {
+  const tooltip = useTooltip(props)
+
+  if (!props.useDelayGroup) {
+    return (
+      <TooltipContext.Provider value={tooltip}>
+        {children}
+      </TooltipContext.Provider>
+    )
+  }
+
+  return (
+    <FloatingDelayGroup
+      delay={{ open: props.delay ?? 0, close: props.closeDelay ?? 0 }}
+      timeoutMs={props.timeout}
+    >
+      <TooltipContext.Provider value={tooltip}>
+        {children}
+      </TooltipContext.Provider>
+    </FloatingDelayGroup>
+  )
+}
+
+export const TooltipTrigger = forwardRef<HTMLElement, TooltipTriggerProps>(
+  function TooltipTrigger({ children, asChild = false, ...props }, propRef) {
+    const context = useTooltipContext()
+    const childrenRef = isValidElement(children)
+      ? parseInt(version, 10) >= 19
+        ? // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          (children as { props: { ref?: React.Ref<any> } }).props.ref
+        : // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          (children as any).ref
+      : undefined
+    const ref = useMergeRefs([context.refs.setReference, propRef, childrenRef])
+
+    if (asChild && isValidElement(children)) {
+      const dataAttributes = {
+        "data-tooltip-state": context.open ? "open" : "closed",
+      }
+
+      return cloneElement(
+        children,
+        context.getReferenceProps({
+          ref,
+          ...props,
+          ...(typeof children.props === "object" ? children.props : {}),
+          ...dataAttributes,
+        })
+      )
+    }
+
+    return (
+      <button
+        ref={ref}
+        data-tooltip-state={context.open ? "open" : "closed"}
+        {...context.getReferenceProps(props)}
+      >
+        {children}
+      </button>
+    )
+  }
+)
+
+export const TooltipContent = forwardRef<HTMLDivElement, TooltipContentProps>(
+  function TooltipContent(
+    { style, children, portal = true, portalProps = {}, ...props },
+    propRef
+  ) {
+    const context = useTooltipContext()
+    const ref = useMergeRefs([context.refs.setFloating, propRef])
+
+    if (!context.open) return null
+
+    const content = (
+      <div
+        ref={ref}
+        style={{
+          ...context.floatingStyles,
+          ...style,
+        }}
+        {...context.getFloatingProps(props)}
+        className="tiptap-tooltip"
+      >
+        {children}
+      </div>
+    )
+
+    if (portal) {
+      return <FloatingPortal {...portalProps}>{content}</FloatingPortal>
+    }
+
+    return content
+  }
+)
+
+Tooltip.displayName = "Tooltip"
+TooltipTrigger.displayName = "TooltipTrigger"
+TooltipContent.displayName = "TooltipContent"

package/src/components/tiptap-ui-utils/floating-element/floating-element-utils.ts

@@ -0,0 +1,23 @@
+import type { Editor } from "@tiptap/react"
+
+export const isElementWithinEditor = (
+  editor: Editor | null,
+  element: Node | null
+) => {
+  if (!element || !editor) {
+    return false
+  }
+
+  const editorWrapper = editor.view.dom.parentElement
+  const editorDom = editor.view.dom
+
+  if (!editorWrapper) {
+    return false
+  }
+
+  return (
+    editorWrapper === element ||
+    editorDom === element ||
+    editorWrapper.contains(element)
+  )
+}

package/src/components/tiptap-ui-utils/floating-element/floating-element.tsx

@@ -0,0 +1,343 @@
+"use client"
+
+import type { HTMLAttributes } from "react"
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react"
+import { type Editor } from "@tiptap/react"
+import {
+  flip,
+  offset,
+  shift,
+  useMergeRefs,
+  type UseFloatingOptions,
+} from "@floating-ui/react"
+import { Selection } from "@tiptap/pm/state"
+
+// --- Hooks ---
+import { useTiptapEditor } from "../../../hooks/use-tiptap-editor"
+import { useFloatingElement } from "../../../hooks/use-floating-element"
+
+// --- Lib ---
+import {
+  getSelectionBoundingRect,
+  isSelectionValid,
+} from "../../../lib/tiptap-collab-utils"
+
+import { isElementWithinEditor } from "./"
+import { isValidPosition } from "../../../lib/tiptap-utils"
+
+export interface FloatingElementProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * The Tiptap editor instance to attach to.
+   */
+  editor?: Editor | null
+  /**
+   * Controls whether the floating element should be visible.
+   * @default undefined
+   */
+  shouldShow?: boolean
+  /**
+   * Additional options to pass to the floating UI.
+   */
+  floatingOptions?: Partial<UseFloatingOptions>
+  /**
+   * Z-index for the floating element.
+   * @default 50
+   */
+  zIndex?: number
+  /**
+   * Callback fired when the visibility state changes.
+   */
+  onOpenChange?: (open: boolean) => void
+  /**
+   * Reference element to position the floating element relative to.
+   * If provided, this takes precedence over getBoundingClientRect.
+   */
+  referenceElement?: HTMLElement | null
+  /**
+   * Custom function to determine the position of the floating element.
+   * Only used if referenceElement is not provided.
+   * @default getSelectionBoundingRect
+   */
+  getBoundingClientRect?: (editor: Editor) => DOMRect | null
+  /**
+   * Whether to close the floating element when Escape key is pressed.
+   * @default true
+   */
+  closeOnEscape?: boolean
+}
+
+/**
+ * A floating UI element that positions itself relative to the current selection in a Tiptap editor.
+ * Used for floating toolbars, menus, and other UI elements that need to appear near the text cursor.
+ */
+export const FloatingElement = forwardRef<HTMLDivElement, FloatingElementProps>(
+  (
+    {
+      editor: providedEditor,
+      shouldShow = undefined,
+      floatingOptions,
+      zIndex = 50,
+      onOpenChange,
+      referenceElement,
+      getBoundingClientRect = getSelectionBoundingRect,
+      closeOnEscape = true,
+      children,
+      style: propStyle,
+      ...props
+    },
+    forwardedRef
+  ) => {
+    const [open, setOpen] = useState<boolean>(
+      shouldShow !== undefined ? shouldShow : false
+    )
+
+    const floatingElementRef = useRef<HTMLDivElement | null>(null)
+    const preventHideRef = useRef(false)
+    const preventShowRef = useRef(false)
+    const editorRef = useRef<Editor | null>(null)
+    const getBoundingClientRectRef = useRef(getBoundingClientRect)
+
+    const { editor } = useTiptapEditor(providedEditor)
+
+    // Keep refs up to date
+    useEffect(() => {
+      editorRef.current = editor
+      getBoundingClientRectRef.current = getBoundingClientRect
+    }, [editor, getBoundingClientRect])
+
+    const handleOpenChange = useCallback(
+      (newOpen: boolean) => {
+        onOpenChange?.(newOpen)
+        setOpen(newOpen)
+      },
+      [onOpenChange]
+    )
+
+    const handleFloatingOpenChange = (open: boolean) => {
+      if (!open && editor) {
+        // When the floating element closes, reset the selection.
+        // This lets the user place the cursor again and ensures the drag handle reappears,
+        // as it's intentionally hidden during valid text selections.
+        const tr = editor.state.tr.setSelection(
+          Selection.near(editor.state.doc.resolve(0))
+        )
+        editor.view.dispatch(tr)
+      }
+
+      handleOpenChange(open)
+    }
+
+    // Use referenceElement if provided, otherwise create dynamic rect function
+    const reference = useMemo(() => {
+      if (referenceElement) {
+        return referenceElement
+      }
+
+      return () => {
+        if (!editorRef.current) return null
+        return getBoundingClientRectRef.current(editorRef.current)
+      }
+    }, [referenceElement])
+
+    const { isMounted, ref, style, getFloatingProps } = useFloatingElement(
+      open,
+      reference,
+      zIndex,
+      {
+        placement: "top",
+        middleware: [shift(), flip(), offset(4)],
+        onOpenChange: handleFloatingOpenChange,
+        dismissOptions: {
+          enabled: true,
+          escapeKey: true,
+          outsidePress(event) {
+            const relatedTarget = event.target as Node
+            if (!relatedTarget) return false
+
+            return !isElementWithinEditor(editor, relatedTarget)
+          },
+        },
+        ...floatingOptions,
+      }
+    )
+
+    const updateSelectionState = useCallback(() => {
+      if (!editor) return
+
+      const newRect = getBoundingClientRect(editor)
+
+      if (newRect && shouldShow !== undefined && !preventShowRef.current) {
+        handleOpenChange(shouldShow)
+        return
+      }
+
+      const shouldShowResult = isSelectionValid(editor)
+
+      if (
+        newRect &&
+        !preventShowRef.current &&
+        (shouldShowResult || preventHideRef.current)
+      ) {
+        handleOpenChange(true)
+      } else if (
+        !preventHideRef.current &&
+        (!shouldShowResult || preventShowRef.current || !editor.isEditable)
+      ) {
+        handleOpenChange(false)
+      }
+    }, [editor, getBoundingClientRect, handleOpenChange, shouldShow])
+
+    useEffect(() => {
+      if (!editor || !closeOnEscape) return
+
+      const handleKeyDown = (event: KeyboardEvent) => {
+        if (event.key === "Escape" && open) {
+          handleOpenChange(false)
+          return true
+        }
+        return false
+      }
+
+      editor.view.dom.addEventListener("keydown", handleKeyDown)
+      return () => {
+        editor.view.dom.removeEventListener("keydown", handleKeyDown)
+      }
+    }, [editor, open, closeOnEscape, handleOpenChange])
+
+    useEffect(() => {
+      if (!editor) return
+
+      const handleBlur = (event: FocusEvent) => {
+        if (preventHideRef.current) {
+          preventHideRef.current = false
+          return
+        }
+
+        const relatedTarget = event.relatedTarget as Node
+        if (!relatedTarget) return
+
+        const isWithinEditor = isElementWithinEditor(editor, relatedTarget)
+
+        const floatingElement = floatingElementRef.current
+        const isWithinFloatingElement =
+          floatingElement &&
+          (floatingElement === relatedTarget ||
+            floatingElement.contains(relatedTarget))
+
+        if (!isWithinEditor && !isWithinFloatingElement && open) {
+          handleOpenChange(false)
+        }
+      }
+
+      editor.view.dom.addEventListener("blur", handleBlur)
+      return () => {
+        editor.view.dom.removeEventListener("blur", handleBlur)
+      }
+    }, [editor, handleOpenChange, open])
+
+    useEffect(() => {
+      if (!editor) return
+
+      const handleDrag = () => {
+        if (open) {
+          handleOpenChange(false)
+        }
+      }
+
+      editor.view.dom.addEventListener("dragstart", handleDrag)
+      editor.view.dom.addEventListener("dragover", handleDrag)
+
+      return () => {
+        editor.view.dom.removeEventListener("dragstart", handleDrag)
+        editor.view.dom.removeEventListener("dragover", handleDrag)
+      }
+    }, [editor, open, handleOpenChange])
+
+    useEffect(() => {
+      if (!editor) return
+
+      const handleMouseDown = (event: MouseEvent) => {
+        if (event.button !== 0) return
+
+        preventShowRef.current = true
+
+        const { state, view } = editor
+        const posCoords = view.posAtCoords({
+          left: event.clientX,
+          top: event.clientY,
+        })
+
+        if (!posCoords || !isValidPosition(posCoords.pos)) return
+
+        const $pos = state.doc.resolve(posCoords.pos)
+        const nodeBefore = $pos.nodeBefore
+
+        if (!nodeBefore || nodeBefore.isBlock) return
+
+        const tr = state.tr.setSelection(
+          Selection.near(state.doc.resolve(posCoords.pos))
+        )
+        view.dispatch(tr)
+      }
+
+      const handleMouseUp = () => {
+        if (preventShowRef.current) {
+          preventShowRef.current = false
+          updateSelectionState()
+        }
+      }
+
+      editor.view.dom.addEventListener("mousedown", handleMouseDown)
+      editor.view.root.addEventListener("mouseup", handleMouseUp)
+
+      return () => {
+        editor.view.dom.removeEventListener("mousedown", handleMouseDown)
+        editor.view.root.removeEventListener("mouseup", handleMouseUp)
+      }
+    }, [editor, updateSelectionState])
+
+    useEffect(() => {
+      if (!editor) return
+
+      editor.on("selectionUpdate", updateSelectionState)
+
+      return () => {
+        editor.off("selectionUpdate", updateSelectionState)
+      }
+    }, [editor, updateSelectionState])
+
+    useEffect(() => {
+      if (!editor) return
+      updateSelectionState()
+    }, [editor, updateSelectionState])
+
+    const finalStyle = useMemo(
+      () =>
+        propStyle && Object.keys(propStyle).length > 0 ? propStyle : style,
+      [propStyle, style]
+    )
+    const mergedRef = useMergeRefs([ref, forwardedRef, floatingElementRef])
+
+    if (!editor || !isMounted || !open) return null
+
+    return (
+      <div
+        ref={mergedRef}
+        style={finalStyle}
+        {...props}
+        {...getFloatingProps()}
+      >
+        {children}
+      </div>
+    )
+  }
+)
+
+FloatingElement.displayName = "FloatingElement"

package/src/components/tiptap-ui-utils/floating-element/index.tsx

@@ -0,0 +1,2 @@
+export * from "./floating-element"
+export * from "./floating-element-utils"

package/src/components/tiptap-ui-utils/suggestion-menu/index.tsx

@@ -0,0 +1,3 @@
+export * from "./suggestion-menu"
+export * from "./suggestion-menu-types"
+export * from "./suggestion-menu-utils"

package/src/components/tiptap-ui-utils/suggestion-menu/suggestion-menu-types.ts

@@ -0,0 +1,91 @@
+import type { UseFloatingOptions } from "@floating-ui/react"
+import type { PluginKey } from "@tiptap/pm/state"
+import type { SuggestionOptions } from "@tiptap/suggestion"
+import type { Editor, Range } from "@tiptap/react"
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type DefaultContext = any
+
+type IconProps = React.SVGProps<SVGSVGElement>
+type IconComponent = ({ className, ...props }: IconProps) => React.ReactElement
+
+export interface SuggestionItem<T = DefaultContext> {
+  /**
+   * The main text to display for the suggestion.
+   */
+  title: string
+  /**
+   * Secondary text to provide additional context.
+   */
+  subtext?: string
+  /**
+   * Icon or badge to display alongside the suggestion.
+   */
+  badge?:
+    | React.MemoExoticComponent<IconComponent>
+    | React.FC<IconProps>
+    | string
+  /**
+   * Group identifier for organizing suggestions.
+   */
+  group?: string
+  /**
+   * Additional keywords for filtering suggestions.
+   */
+  keywords?: string[]
+  /**
+   * Custom data to pass to the onSelect handler.
+   */
+  context?: T
+  /**
+   * Callback executed when this suggestion is selected.
+   */
+  onSelect: (props: { editor: Editor; range: Range; context?: T }) => void
+}
+
+export type SuggestionMenuRenderProps<T = DefaultContext> = {
+  /**
+   * List of suggestion items to display.
+   */
+  items: SuggestionItem<T>[]
+  /**
+   * Index of the currently selected item.
+   */
+  selectedIndex?: number
+  /**
+   * Callback to select an item.
+   */
+  onSelect: (item: SuggestionItem<T>) => void
+}
+
+export interface SuggestionMenuProps<T = DefaultContext>
+  extends Omit<SuggestionOptions<SuggestionItem<T>>, "pluginKey" | "editor"> {
+  /**
+   * The Tiptap editor instance.
+   */
+  editor?: Editor | null
+  /**
+   * Additional options for the floating UI.
+   */
+  floatingOptions?: Partial<UseFloatingOptions>
+  /**
+   * CSS selector attribute for targeting the menu.
+   * @default 'tiptap-suggestion-menu'
+   */
+  selector?: string
+  /**
+   * Unique key for the suggestion plugin.
+   * @default SuggestionPluginKey
+   */
+  pluginKey?: string | PluginKey
+  /**
+   * Maximum height of the suggestion menu.
+   * If provided, the menu will scroll if content exceeds this height.
+   * @default 384
+   */
+  maxHeight?: number
+  /**
+   * Render function for the menu content.
+   */
+  children: (props: SuggestionMenuRenderProps<T>) => React.ReactNode
+}