@meta-1/editor 0.0.29 → 1.0.0

package/src/lib/tiptap-advanced-utils.ts

@@ -0,0 +1,362 @@
+import type { Attrs, Node } from "@tiptap/pm/model"
+import { type Editor } from "@tiptap/react"
+import { NodeSelection, TextSelection } from "@tiptap/pm/state"
+import { findNodePosition, isValidPosition } from "./tiptap-utils"
+
+/**
+ * Splits an array into chunks of specified size
+ */
+export function chunkArray<T>(array: Array<T>, size: number): Array<Array<T>> {
+  return Array.from({ length: Math.ceil(array.length / size) }, (_, index) =>
+    array.slice(index * size, index * size + size)
+  )
+}
+
+/**
+ * Helper function to check if there's content above the current position
+ */
+export function hasContentAbove(editor: Editor | null): {
+  hasContent: boolean
+  content: string
+} {
+  if (!editor) return { hasContent: false, content: "" }
+
+  const { state } = editor
+  const { $from } = state.selection
+
+  for (let i = $from.index(0) - 1; i >= 0; i--) {
+    const node = state.doc.child(i)
+    const content = node.textContent.trim()
+
+    if (content) {
+      return { hasContent: true, content }
+    }
+  }
+
+  return { hasContent: false, content: "" }
+}
+
+/**
+ * Gets the active attributes of a specific mark in the current editor selection.
+ *
+ * @param editor - The Tiptap editor instance.
+ * @param markName - The name of the mark to look for (e.g., "highlight", "link").
+ * @returns The attributes of the active mark, or `null` if the mark is not active.
+ */
+export function getActiveMarkAttrs(
+  editor: Editor | null,
+  markName: string
+): Attrs | null {
+  if (!editor) return null
+
+  const { state } = editor
+  const { from, to, empty, $from } = state.selection
+
+  if (empty) {
+    const mark = $from.marks().find((m) => m.type.name === markName)
+    return mark?.attrs ?? null
+  }
+
+  const seen = new Set<string>()
+  let foundAttrs: Attrs | null = null
+
+  state.doc.nodesBetween(from, to, (node) => {
+    if (!node.isText) return
+
+    for (const mark of node.marks) {
+      if (mark.type.name === markName && !seen.has(mark.type.name)) {
+        seen.add(mark.type.name)
+        foundAttrs = mark.attrs
+      }
+    }
+  })
+
+  return foundAttrs
+}
+
+/**
+ * Finds the position of a node in the editor selection
+ * @param params Object containing editor, node (optional), and nodePos (optional)
+ * @returns The position of the node in the selection or null if not found
+ */
+export function findSelectionPosition(params: {
+  editor: Editor
+  node?: Node | null
+  nodePos?: number | null
+}): number | null {
+  const { editor, node, nodePos } = params
+
+  if (isValidPosition(nodePos)) return nodePos
+
+  if (node) {
+    const found = findNodePosition({ editor, node })
+    if (found) return found.pos
+  }
+
+  const { selection } = editor.state
+  if (!selection.empty) return null
+
+  const resolvedPos = selection.$anchor
+  const nodeDepth = 1
+  const selectedNode = resolvedPos.node(nodeDepth)
+
+  return selectedNode ? resolvedPos.before(nodeDepth) : null
+}
+
+/**
+ * Gets the currently selected DOM element in the editor
+ * @param editor The Tiptap editor instance
+ * @returns The selected DOM element or null if no selection is present
+ */
+export function getSelectedDOMElement(editor: Editor): HTMLElement | null {
+  const { state, view } = editor
+  const { selection } = state
+
+  if (selection instanceof NodeSelection) {
+    return view.nodeDOM(selection.from) as HTMLElement | null
+  }
+
+  if (selection instanceof TextSelection) {
+    const $anchor = selection.$anchor
+
+    // Ensure the depth is sufficient to avoid errors
+    if ($anchor.depth >= 1) {
+      const dom = view.nodeDOM($anchor.before(1))
+      if (dom instanceof HTMLElement) {
+        return dom
+      }
+    }
+  }
+
+  return null
+}
+
+/**
+ * Gets the closest node from the current selection in the editor based on criteria
+ * @param editor The Tiptap editor instance
+ * @param options Configuration options for finding the node
+ * @returns An object containing the closest matching node, its position, and depth, or null if not found
+ */
+export function getClosestNode(
+  editor: Editor | null,
+  options?: {
+    nodeName?: string
+    isBlock?: boolean
+    predicate?: (node: Node) => boolean
+  }
+) {
+  if (!editor) return null
+
+  const { selection } = editor.state
+  const { $from } = selection
+  const { nodeName, isBlock = true, predicate } = options || {} // Default to block nodes
+
+  let depth = $from.depth
+  while (depth > 0) {
+    const node = $from.node(depth)
+
+    // Check all conditions
+    const matchesName = !nodeName || node.type.name === nodeName
+    const matchesBlock = node.type.isBlock === isBlock
+    const matchesPredicate = !predicate || predicate(node)
+
+    if (matchesName && matchesBlock && matchesPredicate) {
+      const pos = $from.before(depth)
+      return { node, pos, depth }
+    }
+    depth--
+  }
+  return null
+}
+
+/**
+ * Gets the closest node from a specific position in the document
+ * @param editor The Tiptap editor instance
+ * @param pos The position to search from
+ * @param options Configuration options for finding the node
+ * @returns An object containing the closest matching node, its position, and depth, or null if not found
+ */
+export function getClosestNodeByPos(
+  editor: Editor | null,
+  pos: number,
+  options?: {
+    nodeName?: string
+    isBlock?: boolean
+    predicate?: (node: Node) => boolean
+  }
+) {
+  if (!editor) return null
+
+  const docSize = editor.state.doc.content.size
+  if (pos < 0 || pos > docSize) {
+    console.warn(`Position ${pos} is out of bounds (doc size: ${docSize})`)
+    return null
+  }
+
+  try {
+    const $pos = editor.state.doc.resolve(pos)
+    const { nodeName, isBlock = true, predicate } = options || {}
+
+    let depth = $pos.depth
+    while (depth > 0) {
+      const node = $pos.node(depth)
+
+      const matchesName = !nodeName || node.type.name === nodeName
+      const matchesBlock = node.type.isBlock === isBlock
+      const matchesPredicate = !predicate || predicate(node)
+
+      if (matchesName && matchesBlock && matchesPredicate) {
+        const nodePos = $pos.before(depth)
+        return { node, pos: nodePos, depth }
+      }
+      depth--
+    }
+    return null
+  } catch (error) {
+    console.error("Error resolving position:", error)
+    return null
+  }
+}
+
+/**
+ * Convenience function to find closest block node (maintains backward compatibility)
+ */
+export function getClosestBlockNode(editor: Editor | null) {
+  return getClosestNode(editor, { isBlock: true })
+}
+
+/**
+ * Convenience function to find closest node by name
+ */
+export function getClosestNodeByName(editor: Editor | null, nodeName: string) {
+  return getClosestNode(editor, { nodeName })
+}
+
+/**
+ * Find multiple matching nodes up the tree
+ */
+export function getAllMatchingNodes(
+  editor: Editor | null,
+  options?: {
+    nodeName?: string
+    isBlock?: boolean
+    predicate?: (node: Node) => boolean
+  }
+) {
+  if (!editor) return []
+
+  const { selection } = editor.state
+  const { nodeName, isBlock = true, predicate } = options || {}
+  const matches = []
+
+  const nodeMatches = (node: Node) => {
+    const matchesName = !nodeName || node.type.name === nodeName
+    const matchesBlock = node.type.isBlock === isBlock
+    const matchesPredicate = !predicate || predicate(node)
+    return matchesName && matchesBlock && matchesPredicate
+  }
+
+  if (selection instanceof NodeSelection) {
+    const selectedNode = selection.node
+    if (nodeMatches(selectedNode)) {
+      matches.push({
+        node: selectedNode,
+        pos: selection.from,
+        depth: 0,
+      })
+    }
+  }
+
+  const { $from } = selection
+  let depth = $from.depth
+
+  while (depth > 0) {
+    const node = $from.node(depth)
+
+    if (nodeMatches(node)) {
+      const pos = $from.before(depth)
+      matches.push({ node, pos, depth })
+    }
+    depth--
+  }
+
+  return matches
+}
+
+/**
+ * Gets the anchor node and its position in the editor.
+ * @param editor The Tiptap editor instance
+ * @param allowEmptySelection If true, still returns the node at the cursor position even if selection is empty
+ * @returns An object containing the anchor node and its position, or null if not found
+ */
+export function getAnchorNodeAndPos(
+  editor: Editor | null,
+  allowEmptySelection: boolean = true
+): { node: Node; pos: number } | null {
+  if (!editor) return null
+
+  const { state } = editor
+  const { selection } = state
+
+  if (selection instanceof NodeSelection) {
+    const node = selection.node
+    const pos = selection.from
+
+    if (node && isValidPosition(pos)) {
+      return { node, pos }
+    }
+  }
+
+  if (selection.empty && !allowEmptySelection) return null
+
+  const $anchor = selection.$anchor
+  const depth = 1 // explicitly use depth 1
+  const node = $anchor.node(depth)
+  const pos = $anchor.before(depth)
+
+  return { node, pos }
+}
+
+/**
+ * Checks if the current selection in the editor contains any text.
+ *
+ * @param editor - The Tiptap editor instance.
+ * @returns `true` if the selection contains text, `false` otherwise.
+ */
+export function selectionHasText(editor: Editor | null): boolean {
+  if (!editor) return false
+
+  const { state } = editor
+  const { selection, doc } = state
+
+  if (selection.empty) return false
+
+  const text = doc.textBetween(selection.from, selection.to, "\n", "\0")
+  return text.trim().length > 0
+}
+
+/**
+ * Retrieves a specific extension by name from the Tiptap editor.
+ * @param editor - The Tiptap editor instance
+ * @param extensionName - The name of the extension to retrieve
+ * @returns The extension instance if found, otherwise null
+ */
+export function getEditorExtension(
+  editor: Editor | null,
+  extensionName: string
+) {
+  if (!editor) return null
+
+  const extension = editor.extensionManager.extensions.find(
+    (ext) => ext.name === extensionName
+  )
+
+  if (!extension) {
+    console.warn(
+      `Extension "${extensionName}" not found in the editor schema. Ensure it is included in the editor configuration.`
+    )
+    return null
+  }
+
+  return extension
+}

package/src/lib/tiptap-collab-utils.ts

@@ -0,0 +1,289 @@
+import { NodeSelection, type Selection } from "@tiptap/pm/state"
+import { CellSelection } from "@tiptap/pm/tables"
+import type { JSONContent, Editor } from "@tiptap/react"
+import { isTextSelection, isNodeSelection, posToDOMRect } from "@tiptap/react"
+
+// TipTap Collaboration
+export const TIPTAP_COLLAB_DOC_PREFIX =
+  process.env.NEXT_PUBLIC_TIPTAP_COLLAB_DOC_PREFIX || ""
+export const TIPTAP_COLLAB_APP_ID =
+  process.env.NEXT_PUBLIC_TIPTAP_COLLAB_APP_ID || ""
+export const TIPTAP_COLLAB_TOKEN =
+  process.env.NEXT_PUBLIC_TIPTAP_COLLAB_TOKEN || ""
+
+// TipTap AI
+export const TIPTAP_AI_APP_ID = process.env.NEXT_PUBLIC_TIPTAP_AI_APP_ID || ""
+export const TIPTAP_AI_TOKEN = process.env.NEXT_PUBLIC_TIPTAP_AI_TOKEN || ""
+
+export const USE_JWT_TOKEN_API_ENDPOINT =
+  process.env.NEXT_PUBLIC_USE_JWT_TOKEN_API_ENDPOINT || ""
+
+const NODE_TYPE_LABELS: Record<string, string> = {
+  paragraph: "Text",
+  heading: "Heading",
+  blockquote: "Blockquote",
+  listItem: "List Item",
+  codeBlock: "Code Block",
+  table: "Table",
+}
+export type OverflowPosition = "none" | "top" | "bottom" | "both"
+
+/**
+ * Utility function to get URL parameters
+ */
+export const getUrlParam = (param: string): string | null => {
+  if (typeof window === "undefined") return null
+  const params = new URLSearchParams(window.location.search)
+  return params.get(param)
+}
+
+/**
+ * Returns a display name for the current node in the editor
+ * @param editor The Tiptap editor instance
+ * @returns The display name of the current node
+ */
+export const getNodeDisplayName = (editor: Editor | null): string => {
+  if (!editor) return "Node"
+
+  const { selection } = editor.state
+
+  if (selection instanceof NodeSelection) {
+    const nodeType = selection.node.type.name
+    return NODE_TYPE_LABELS[nodeType] || nodeType.toLowerCase()
+  }
+
+  if (selection instanceof CellSelection) {
+    return "Table"
+  }
+
+  const { $anchor } = selection
+  const nodeType = $anchor.parent.type.name
+  return NODE_TYPE_LABELS[nodeType] || nodeType.toLowerCase()
+}
+
+/**
+ * Removes empty paragraph nodes from content
+ */
+export const removeEmptyParagraphs = (content: JSONContent) => ({
+  ...content,
+  content: content.content?.filter(
+    (node) =>
+      node.type !== "paragraph" ||
+      node.content?.some((child) => child.text?.trim() || child.type !== "text")
+  ),
+})
+
+/**
+ * Determines how a target element overflows relative to a container element
+ */
+export function getElementOverflowPosition(
+  targetElement: Element,
+  containerElement: HTMLElement
+): OverflowPosition {
+  const targetBounds = targetElement.getBoundingClientRect()
+  const containerBounds = containerElement.getBoundingClientRect()
+
+  const isOverflowingTop = targetBounds.top < containerBounds.top
+  const isOverflowingBottom = targetBounds.bottom > containerBounds.bottom
+
+  if (isOverflowingTop && isOverflowingBottom) return "both"
+  if (isOverflowingTop) return "top"
+  if (isOverflowingBottom) return "bottom"
+  return "none"
+}
+
+/**
+ * Checks if the current selection is valid for a given editor
+ */
+export const isSelectionValid = (
+  editor: Editor | null,
+  selection?: Selection,
+  excludedNodeTypes: string[] = ["imageUpload", "horizontalRule"]
+): boolean => {
+  if (!editor) return false
+  if (!selection) selection = editor.state.selection
+
+  const { state } = editor
+  const { doc } = state
+  const { empty, from, to } = selection
+
+  const isEmptyTextBlock =
+    !doc.textBetween(from, to).length && isTextSelection(selection)
+  const isCodeBlock =
+    selection.$from.parent.type.spec.code ||
+    (isNodeSelection(selection) && selection.node.type.spec.code)
+  const isExcludedNode =
+    isNodeSelection(selection) &&
+    excludedNodeTypes.includes(selection.node.type.name)
+  const isTableCell = selection instanceof CellSelection
+
+  return (
+    !empty &&
+    !isEmptyTextBlock &&
+    !isCodeBlock &&
+    !isExcludedNode &&
+    !isTableCell
+  )
+}
+
+/**
+ * Checks if the current text selection is valid for editing
+ * - Not empty
+ * - Not a code block
+ * - Not a node selection
+ */
+export const isTextSelectionValid = (editor: Editor | null): boolean => {
+  if (!editor) return false
+  const { state } = editor
+  const { selection } = state
+  const isValid =
+    isTextSelection(selection) &&
+    !selection.empty &&
+    !selection.$from.parent.type.spec.code &&
+    !isNodeSelection(selection)
+
+  return isValid
+}
+
+/**
+ * Gets the bounding rect of the current selection in the editor.
+ */
+export const getSelectionBoundingRect = (editor: Editor): DOMRect | null => {
+  const { state } = editor.view
+  const { selection } = state
+  const { ranges } = selection
+
+  const from = Math.min(...ranges.map((range) => range.$from.pos))
+  const to = Math.max(...ranges.map((range) => range.$to.pos))
+
+  if (isNodeSelection(selection)) {
+    const node = editor.view.nodeDOM(from) as HTMLElement
+    if (node) {
+      return node.getBoundingClientRect()
+    }
+  }
+
+  return posToDOMRect(editor.view, from, to)
+}
+
+/**
+ * Generates a deterministic avatar URL from a user name
+ */
+export const getAvatar = (name: string) => {
+  if (!name) {
+    return "/avatars/memoji_01.png"
+  }
+
+  let hash = 0
+  for (let i = 0; i < name.length; i++) {
+    hash = name.charCodeAt(i) + ((hash << 5) - hash)
+    hash = hash & hash
+  }
+
+  const randomFraction = (Math.abs(hash) % 1000000) / 1000000
+  const id = 1 + Math.floor(randomFraction * 20)
+  const idString = id.toString().padStart(2, "0")
+  return `/avatars/memoji_${idString}.png`
+}
+
+/**
+ * Fetch collaboration JWT token from the API
+ */
+export const fetchCollabToken = async () => {
+  if (USE_JWT_TOKEN_API_ENDPOINT) {
+    try {
+      // Example API endpoint that returns a JWT token.
+      // TODO: implement this API endpoint in your app
+      const response = await fetch(`/api/collaboration`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+      })
+
+      if (!response.ok) {
+        throw new Error(`Failed to fetch token: ${response.status}`)
+      }
+
+      const data = await response.json()
+      return data.token
+    } catch (error) {
+      console.error("Failed to fetch collaboration token:", error)
+      return null
+    }
+  }
+
+  // TODO: as a developer, use the example JWT token provided in the Tiptap
+  // Cloud dashboard for local development only. In production, implement an API
+  // endpoint that generates a new JWT token in the server. Then, call that API
+  // endpoint from this function.
+  // When you've implemented the API endpoint, remove the code below.
+  if (!TIPTAP_COLLAB_TOKEN) {
+    alert(`Set up your environment variables to connect to Tiptap Cloud:
+- NEXT_PUBLIC_TIPTAP_COLLAB_DOC_PREFIX - Prefix for identifying collaborative documents
+- NEXT_PUBLIC_TIPTAP_COLLAB_APP_ID - Your Document Server App ID
+- NEXT_PUBLIC_TIPTAP_COLLAB_TOKEN - JWT token for accessing Collaboration services (do not use in production)
+- NEXT_PUBLIC_TIPTAP_AI_APP_ID - Your AI App ID
+- NEXT_PUBLIC_TIPTAP_AI_TOKEN - JWT token for accessing AI services (do not use in production)
+Follow this guide: https://tiptap.dev/docs/ui-components/templates/notion-like-editor`)
+  } else {
+    console.warn(
+      "You are using the example JWT token provided in the Tiptap Cloud dashboard. This is only for local development and should not be used in production. In production, implement an API endpoint that generates a new JWT token in the server, and call that API endpoint from the fetchCollabToken function. More info in the docs: https://tiptap.dev/docs/ui-components/templates/notion-like-editor"
+    )
+  }
+
+  // A hardcoded token for demonstration purposes.
+  // TODO: remove this in production and use the API endpoint instead
+  return TIPTAP_COLLAB_TOKEN
+}
+
+/**
+ * Fetch AI JWT token from the API
+ */
+export const fetchAiToken = async () => {
+  if (USE_JWT_TOKEN_API_ENDPOINT) {
+    try {
+      // Example API endpoint that returns a JWT token.
+      // TODO: implement this API endpoint in your app
+      const response = await fetch(`/api/ai`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+      })
+
+      if (!response.ok) {
+        throw new Error(`Failed to fetch token: ${response.status}`)
+      }
+
+      const data = await response.json()
+      return data.token
+    } catch (error) {
+      console.error("Failed to fetch AI token:", error)
+      return null
+    }
+  }
+
+  // TODO: as a developer, use the example JWT token provided in the Tiptap
+  // Cloud dashboard for local development only. In production, implement an API
+  // endpoint that generates a new JWT token in the server. Then, call that API
+  // endpoint from this function.
+  // When you've implemented the API endpoint, remove the code below.
+  if (!TIPTAP_AI_TOKEN) {
+    alert(`Set up your environment variables to connect to Tiptap Cloud:
+- NEXT_PUBLIC_TIPTAP_COLLAB_DOC_PREFIX - Prefix for identifying collaborative documents
+- NEXT_PUBLIC_TIPTAP_COLLAB_APP_ID - Your Document Server App ID
+- NEXT_PUBLIC_TIPTAP_COLLAB_TOKEN - JWT token for accessing Collaboration services (do not use in production)
+- NEXT_PUBLIC_TIPTAP_AI_APP_ID - Your AI App ID
+- NEXT_PUBLIC_TIPTAP_AI_TOKEN - JWT token for accessing AI services (do not use in production)
+Follow this guide: https://tiptap.dev/docs/ui-components/templates/notion-like-editor`)
+  } else {
+    console.warn(
+      "You are using the example JWT token provided in the Tiptap Cloud dashboard. This is only for local development and should not be used in production. In production, implement an API endpoint that generates a new JWT token in the server, and call that API endpoint from the fetchAiToken function. More info in the docs: https://tiptap.dev/docs/ui-components/templates/notion-like-editor"
+    )
+  }
+
+  // A hardcoded token for demonstration purposes.
+  // TODO: remove this in production and use the API endpoint instead
+  return TIPTAP_AI_TOKEN
+}