@allbluecn/web-app 0.6.3 → 0.7.0

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

@@ -0,0 +1,362 @@
+import { getClientI18n } from '@/i18n/client'
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+
+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.ts"
+import { useIsBreakpoint } from "../../hooks/use-is-breakpoint.ts"
+
+// --- Lib ---
+import {
+  findNodePosition,
+  isNodeTypeSelected,
+  isValidPosition,
+} from "../../lib/utils.ts"
+
+// --- Icons ---
+import { AtSignIcon } from "../../icons/at-sign-icon.tsx"
+
+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) return false
+
+  if (!hideWhenUnavailable) {
+    return true
+  }
+
+  if (!editor.isEditable) return false
+
+  if (!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: getClientI18n().t('add-mention'),
+    shortcutKeys: MENTION_TRIGGER_SHORTCUT_KEY,
+    trigger,
+    Icon: AtSignIcon,
+  }
+}

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

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+export * from "./move-node-button"
+export * from "./use-move-node"

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

@@ -0,0 +1,138 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+
+import { forwardRef, useCallback } from "react"
+
+import { useTranslation } from 'react-i18next'
+// --- Lib ---
+import { parseShortcutKeys } from "../../lib/utils.ts"
+
+// --- Hooks ---
+import { useTiptapEditor } from "../../hooks/use-tiptap-editor.ts"
+
+// --- Tiptap UI ---
+import type { UseMoveNodeConfig } from "./index.tsx"
+import { useMoveNode } from "./index.tsx"
+
+// --- UI Primitives ---
+import type { ButtonProps } from "../../ui-primitive/button/index.tsx"
+import { Button } from "../../ui-primitive/button/index.tsx"
+import { Badge } from "../../ui-primitive/badge/index.tsx"
+
+export interface MoveNodeButtonProps
+  extends Omit<ButtonProps, "type">, UseMoveNodeConfig {
+  /**
+   * Optional text to display alongside the icon.
+   */
+  text?: string
+  /**
+   * Optional show shortcut keys in the button.
+   * @default false
+   */
+  showShortcut?: boolean
+}
+
+export function MoveNodeShortcutBadge({
+shortcutKeys,
+}: {
+  shortcutKeys: string
+}) {
+  const { t } = useTranslation('editor')
+  return <Badge>{parseShortcutKeys({ shortcutKeys })}</Badge>
+}
+
+/**
+ * Button component for moving a node up or down in a Tiptap editor.
+ */
+export const MoveNodeButton = forwardRef<
+  HTMLButtonElement,
+  MoveNodeButtonProps
+>(
+  (
+    {
+      editor: providedEditor,
+      text,
+      direction,
+      hideWhenUnavailable = false,
+      onMoved,
+      showShortcut = false,
+      onClick,
+      children,
+      ...buttonProps
+    },
+    ref
+  ) => {
+    const { t } = useTranslation('editor')
+    const { editor } = useTiptapEditor(providedEditor)
+    const {
+      isVisible,
+      handleMoveNode,
+      canMoveNode,
+      label,
+      shortcutKeys,
+      Icon,
+    } = useMoveNode({
+      editor,
+      direction,
+      hideWhenUnavailable,
+      onMoved,
+    })
+
+    const handleClick = useCallback(
+      (event: React.MouseEvent<HTMLButtonElement>) => {
+        onClick?.(event)
+        if (event.defaultPrevented) return
+        handleMoveNode()
+      },
+      [handleMoveNode, onClick]
+    )
+
+    if (!isVisible) {
+      return null
+    }
+
+    const tooltip = direction === "up" ? t('move-up') : t('move-down')
+
+    return (
+      <Button
+        type="button"
+        variant="ghost"
+        role="button"
+        tabIndex={-1}
+        aria-label={label}
+        tooltip={tooltip}
+        disabled={!canMoveNode}
+        onClick={handleClick}
+        {...buttonProps}
+        ref={ref}
+      >
+        {children ?? (
+          <>
+            <Icon className="tiptap-button-icon" />
+            {text && <span className="tiptap-button-text">{text}</span>}
+            {showShortcut && (
+              <MoveNodeShortcutBadge shortcutKeys={shortcutKeys} />
+            )}
+          </>
+        )}
+      </Button>
+    )
+  }
+)
+
+MoveNodeButton.displayName = "MoveNodeButton"