@allbluecn/web-app 0.6.3 → 0.7.0

package/src/components/tiptap/hooks/use-is-breakpoint.ts

@@ -0,0 +1,53 @@
+// 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 { useEffect, useState } from "react"
+
+type BreakpointMode = "min" | "max"
+
+/**
+ * Hook to detect whether the current viewport matches a given breakpoint rule.
+ * Example:
+ *   useIsBreakpoint("max", 768)   // true when width < 768
+ *   useIsBreakpoint("min", 1024)  // true when width >= 1024
+ */
+export function useIsBreakpoint(
+  mode: BreakpointMode = "max",
+  breakpoint = 768
+) {
+  const [matches, setMatches] = useState<boolean | undefined>(undefined)
+
+  useEffect(() => {
+    const query =
+      mode === "min"
+        ? `(min-width: ${breakpoint}px)`
+        : `(max-width: ${breakpoint - 1}px)`
+
+    const mql = window.matchMedia(query)
+    const onChange = (e: MediaQueryListEvent) => setMatches(e.matches)
+
+    // Set initial value
+    setMatches(mql.matches)
+
+    // Add listener
+    mql.addEventListener("change", onChange)
+    return () => mql.removeEventListener("change", onChange)
+  }, [mode, breakpoint])
+
+  return !!matches
+}

package/src/components/tiptap/hooks/use-isomorphic-layout-effect.ts

@@ -0,0 +1,27 @@
+// 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 { useEffect, useLayoutEffect } from "react"
+
+/**
+ * Custom hook that uses either `useLayoutEffect` or `useEffect` based on the environment (client-side or server-side).
+ * @param {Function} effect - The effect function to be executed.
+ * @param {Array<any>} [dependencies] - An array of dependencies for the effect (optional).
+ */
+export const useIsomorphicLayoutEffect =
+  typeof window !== "undefined" ? useLayoutEffect : useEffect

package/src/components/tiptap/hooks/use-menu-navigation.ts

@@ -0,0 +1,212 @@
+// 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 type { Editor } from "@tiptap/react"
+import { useEffect, useState } from "react"
+
+type Orientation = "horizontal" | "vertical" | "both"
+
+interface MenuNavigationOptions<T> {
+  /**
+   * The Tiptap editor instance, if using with a Tiptap editor.
+   */
+  editor?: Editor | null
+  /**
+   * Reference to the container element for handling keyboard events.
+   */
+  containerRef?: React.RefObject<HTMLElement | null>
+  /**
+   * Search query that affects the selected item.
+   */
+  query?: string
+  /**
+   * Array of items to navigate through.
+   */
+  items: T[]
+  /**
+   * Callback fired when an item is selected.
+   */
+  onSelect?: (item: T) => void
+  /**
+   * Callback fired when the menu should close.
+   */
+  onClose?: () => void
+  /**
+   * The navigation orientation of the menu.
+   * @default "vertical"
+   */
+  orientation?: Orientation
+  /**
+   * Whether to automatically select the first item when the menu opens.
+   * @default true
+   */
+  autoSelectFirstItem?: boolean
+}
+
+/**
+ * Hook that implements keyboard navigation for dropdown menus and command palettes.
+ *
+ * Handles arrow keys, tab, home/end, enter for selection, and escape to close.
+ * Works with both Tiptap editors and regular DOM elements.
+ *
+ * @param options - Configuration options for the menu navigation
+ * @returns Object containing the selected index and a setter function
+ */
+export function useMenuNavigation<T>({
+  editor,
+  containerRef,
+  query,
+  items,
+  onSelect,
+  onClose,
+  orientation = "vertical",
+  autoSelectFirstItem = true,
+}: MenuNavigationOptions<T>) {
+  const [selectedIndex, setSelectedIndex] = useState<number>(
+    autoSelectFirstItem ? 0 : -1
+  )
+
+  useEffect(() => {
+    const handleKeyboardNavigation = (event: KeyboardEvent) => {
+      if (!items.length) return false
+
+      const moveNext = () =>
+        setSelectedIndex((currentIndex) => {
+          if (currentIndex === -1) return 0
+          return (currentIndex + 1) % items.length
+        })
+
+      const movePrev = () =>
+        setSelectedIndex((currentIndex) => {
+          if (currentIndex === -1) return items.length - 1
+          return (currentIndex - 1 + items.length) % items.length
+        })
+
+      switch (event.key) {
+        case "ArrowUp": {
+          if (orientation === "horizontal") return false
+          event.preventDefault()
+          movePrev()
+          return true
+        }
+
+        case "ArrowDown": {
+          if (orientation === "horizontal") return false
+          event.preventDefault()
+          moveNext()
+          return true
+        }
+
+        case "ArrowLeft": {
+          if (orientation === "vertical") return false
+          event.preventDefault()
+          movePrev()
+          return true
+        }
+
+        case "ArrowRight": {
+          if (orientation === "vertical") return false
+          event.preventDefault()
+          moveNext()
+          return true
+        }
+
+        case "Tab": {
+          event.preventDefault()
+          if (event.shiftKey) {
+            movePrev()
+          } else {
+            moveNext()
+          }
+          return true
+        }
+
+        case "Home": {
+          event.preventDefault()
+          setSelectedIndex(0)
+          return true
+        }
+
+        case "End": {
+          event.preventDefault()
+          setSelectedIndex(items.length - 1)
+          return true
+        }
+
+        case "Enter": {
+          if (event.isComposing) return false
+          event.preventDefault()
+          if (selectedIndex !== -1 && items[selectedIndex]) {
+            onSelect?.(items[selectedIndex])
+          }
+          return true
+        }
+
+        case "Escape": {
+          event.preventDefault()
+          onClose?.()
+          return true
+        }
+
+        default:
+          return false
+      }
+    }
+
+    let targetElement: HTMLElement | null = null
+
+    if (editor) {
+      targetElement = editor.view.dom
+    } else if (containerRef?.current) {
+      targetElement = containerRef.current
+    }
+
+    if (targetElement) {
+      targetElement.addEventListener("keydown", handleKeyboardNavigation, true)
+
+      return () => {
+        targetElement?.removeEventListener(
+          "keydown",
+          handleKeyboardNavigation,
+          true
+        )
+      }
+    }
+
+    return undefined
+  }, [
+    editor,
+    containerRef,
+    items,
+    selectedIndex,
+    onSelect,
+    onClose,
+    orientation,
+  ])
+
+  useEffect(() => {
+    if (query) {
+      setSelectedIndex(autoSelectFirstItem ? 0 : -1)
+    }
+  }, [query, autoSelectFirstItem])
+
+  return {
+    selectedIndex: items.length ? selectedIndex : undefined,
+    setSelectedIndex,
+  }
+}

package/src/components/tiptap/hooks/use-on-click-outside.ts

@@ -0,0 +1,167 @@
+// 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 type { RefObject } from "react"
+import { useEffect, useRef } from "react"
+import { useIsomorphicLayoutEffect } from "./use-isomorphic-layout-effect.ts"
+
+// MediaQueryList Event based useEventListener interface
+function useEventListener<K extends keyof MediaQueryListEventMap>(
+  eventName: K,
+  handler: (event: MediaQueryListEventMap[K]) => void,
+  element: RefObject<MediaQueryList>,
+  options?: boolean | AddEventListenerOptions
+): void
+
+// Window Event based useEventListener interface
+function useEventListener<K extends keyof WindowEventMap>(
+  eventName: K,
+  handler: (event: WindowEventMap[K]) => void,
+  element?: undefined,
+  options?: boolean | AddEventListenerOptions
+): void
+
+// Element Event based useEventListener interface
+function useEventListener<
+  K extends keyof HTMLElementEventMap & keyof SVGElementEventMap,
+  T extends Element = K extends keyof HTMLElementEventMap
+    ? HTMLDivElement
+    : SVGElement,
+>(
+  eventName: K,
+  handler:
+    | ((event: HTMLElementEventMap[K]) => void)
+    | ((event: SVGElementEventMap[K]) => void),
+  element: RefObject<T>,
+  options?: boolean | AddEventListenerOptions
+): void
+
+// Document Event based useEventListener interface
+function useEventListener<K extends keyof DocumentEventMap>(
+  eventName: K,
+  handler: (event: DocumentEventMap[K]) => void,
+  element: RefObject<Document>,
+  options?: boolean | AddEventListenerOptions
+): void
+
+/**
+ * Custom hook that attaches event listeners to DOM elements, the window, or media query lists.
+ * @template KW - The type of event for window events.
+ * @template KH - The type of event for HTML or SVG element events.
+ * @template KM - The type of event for media query list events.
+ * @template T - The type of the DOM element (default is `HTMLElement`).
+ * @param {KW | KH | KM} eventName - The name of the event to listen for.
+ * @param {(event: WindowEventMap[KW] | HTMLElementEventMap[KH] | SVGElementEventMap[KH] | MediaQueryListEventMap[KM] | Event) => void} handler - The event handler function.
+ * @param {RefObject<T>} [element] - The DOM element or media query list to attach the event listener to (optional).
+ * @param {boolean | AddEventListenerOptions} [options] - An options object that specifies characteristics about the event listener (optional).
+ */
+function useEventListener<
+  KW extends keyof WindowEventMap,
+  KH extends keyof HTMLElementEventMap & keyof SVGElementEventMap,
+  KM extends keyof MediaQueryListEventMap,
+  T extends HTMLElement | SVGAElement | MediaQueryList = HTMLElement,
+>(
+  eventName: KW | KH | KM,
+  handler: (
+    event:
+      | WindowEventMap[KW]
+      | HTMLElementEventMap[KH]
+      | SVGElementEventMap[KH]
+      | MediaQueryListEventMap[KM]
+      | Event
+  ) => void,
+  element?: RefObject<T>,
+  options?: boolean | AddEventListenerOptions
+) {
+  // Create a ref that stores handler
+  const savedHandler = useRef(handler)
+
+  useIsomorphicLayoutEffect(() => {
+    savedHandler.current = handler
+  }, [handler])
+
+  useEffect(() => {
+    // Define the listening target
+    const targetElement: T | Window = element?.current ?? window
+
+    if (!(targetElement && targetElement.addEventListener)) return
+
+    // Create event listener that calls handler function stored in ref
+    const listener: typeof handler = (event) => {
+      savedHandler.current(event)
+    }
+
+    targetElement.addEventListener(eventName, listener, options)
+
+    // Remove event listener on cleanup
+    return () => {
+      targetElement.removeEventListener(eventName, listener, options)
+    }
+  }, [eventName, element, options])
+}
+
+export { useEventListener }
+
+/** Supported event types. */
+type EventType =
+  | "mousedown"
+  | "mouseup"
+  | "touchstart"
+  | "touchend"
+  | "focusin"
+  | "focusout"
+
+/**
+ * Custom hook that handles clicks outside a specified element.
+ * @template T - The type of the element's reference.
+ * @param {RefObject<T> | RefObject<T>[]} ref - The React ref object(s) representing the element(s) to watch for outside clicks.
+ * @param {(event: MouseEvent | TouchEvent | FocusEvent) => void} handler - The callback function to be executed when a click outside the element occurs.
+ * @param {EventType} [eventType] - The mouse event type to listen for (optional, default is 'mousedown').
+ * @param {?AddEventListenerOptions} [eventListenerOptions] - The options object to be passed to the `addEventListener` method (optional).
+ * @returns {void}
+ */
+export function useOnClickOutside<T extends HTMLElement | null = HTMLElement>(
+  ref: RefObject<T> | RefObject<T>[],
+  handler: (event: MouseEvent | TouchEvent | FocusEvent) => void,
+  eventType: EventType = "mousedown",
+  eventListenerOptions: AddEventListenerOptions = {}
+): void {
+  useEventListener(
+    eventType,
+    (event) => {
+      const target = event.target as Node
+
+      // Do nothing if the target is not connected element with document
+      if (!target || !target.isConnected) {
+        return
+      }
+
+      const isOutside = Array.isArray(ref)
+        ? ref
+            .filter((r) => Boolean(r.current))
+            .every((r) => r.current && !r.current.contains(target))
+        : ref.current && !ref.current.contains(target)
+
+      if (isOutside) {
+        handler(event)
+      }
+    },
+    undefined,
+    eventListenerOptions
+  )
+}

package/src/components/tiptap/hooks/use-tiptap-editor.ts

@@ -0,0 +1,87 @@
+// 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 type { Editor } from "@tiptap/react"
+import { useCurrentEditor, useEditorState } from "@tiptap/react"
+import { useEffect, useState } from "react"
+
+function getActivePageEditor(editor: Editor): Editor | null {
+  const storage = editor.storage as unknown as Record<string, unknown>
+  const pages = storage.pages as { activeEditor?: Editor | null } | undefined
+  if (!pages || !("activeEditor" in pages)) return null
+  return pages.activeEditor ?? null
+}
+
+export function useTiptapEditor(providedEditor?: Editor | null): {
+  editor: Editor | null
+  editorState?: Editor["state"]
+  canCommand?: Editor["can"]
+} {
+  const { editor: coreEditor } = useCurrentEditor()
+  const mainEditor = providedEditor ?? coreEditor
+
+  const [storageEditor, setStorageEditor] = useState<Editor | null>(null)
+
+  useEffect(() => {
+    if (!mainEditor) {
+      setStorageEditor(null)
+      return
+    }
+
+    const updateHandler = () =>
+      setStorageEditor(getActivePageEditor(mainEditor))
+
+    updateHandler()
+
+    mainEditor.on("update", updateHandler)
+    mainEditor.on("selectionUpdate", updateHandler)
+
+    return () => {
+      mainEditor.off("update", updateHandler)
+      mainEditor.off("selectionUpdate", updateHandler)
+    }
+  }, [mainEditor])
+
+  useEffect(() => {
+    if (!storageEditor) return
+
+    const handleDestroy = () => setStorageEditor(null)
+
+    storageEditor.on("destroy", handleDestroy)
+    return () => {
+      storageEditor.off("destroy", handleDestroy)
+    }
+  }, [storageEditor])
+
+  const editorState = useEditorState({
+    editor: storageEditor ?? mainEditor,
+    selector(context) {
+      if (!context.editor) {
+        return { editor: null, editorState: undefined, canCommand: undefined }
+      }
+
+      return {
+        editor: context.editor,
+        editorState: context.editor.state,
+        canCommand: context.editor.can,
+      }
+    },
+  })
+
+  return editorState ?? { editor: null }
+}

package/src/components/tiptap/hooks/use-ui-editor-state.ts

@@ -0,0 +1,47 @@
+// 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 type { Editor } from "@tiptap/react"
+import { useEditorState } from "@tiptap/react"
+import {
+  defaultUiState,
+  type UiState,
+} from "../extension/ui-state-extension.ts"
+
+export function useUiEditorState(editor: Editor | null): UiState {
+  return (
+    useEditorState({
+      editor,
+      selector: ({ editor }) => {
+        if (!editor) return defaultUiState
+
+        const state = editor.storage.uiState
+        if (!state) {
+          console.warn(
+            "Editor storage uiState is not initialized. Ensure you have the uiState extension added to your editor."
+          )
+          return defaultUiState
+        }
+
+        return { ...defaultUiState, ...state }
+      },
+    }) ?? defaultUiState
+  )
+}
+
+export default useUiEditorState

package/src/components/tiptap/hooks/use-window-size.ts

@@ -0,0 +1,108 @@
+// 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 { useEffect, useState } from "react"
+import { useThrottledCallback } from "@tanstack/react-pacer"
+
+export interface WindowSizeState {
+  /**
+   * The width of the window's visual viewport in pixels.
+   */
+  width: number
+  /**
+   * The height of the window's visual viewport in pixels.
+   */
+  height: number
+  /**
+   * The distance from the top of the visual viewport to the top of the layout viewport.
+   * Particularly useful for handling mobile keyboard appearance.
+   */
+  offsetTop: number
+  /**
+   * The distance from the left of the visual viewport to the left of the layout viewport.
+   */
+  offsetLeft: number
+  /**
+   * The scale factor of the visual viewport.
+   * This is useful for scaling elements based on the current zoom level.
+   */
+  scale: number
+}
+
+/**
+ * Hook that tracks the window's visual viewport dimensions, position, and provides
+ * a CSS transform for positioning elements.
+ *
+ * Uses the Visual Viewport API to get accurate measurements, especially important
+ * for mobile devices where virtual keyboards can change the visible area.
+ * Only updates state when values actually change to optimize performance.
+ *
+ * @returns An object containing viewport properties and a CSS transform string
+ */
+export function useWindowSize(): WindowSizeState {
+  const [windowSize, setWindowSize] = useState<WindowSizeState>({
+    width: 0,
+    height: 0,
+    offsetTop: 0,
+    offsetLeft: 0,
+    scale: 0,
+  })
+
+  const handleViewportChange = useThrottledCallback(() => {
+    if (typeof window === "undefined") return
+
+    const vp = window.visualViewport
+    if (!vp) return
+
+    const {
+      width = 0,
+      height = 0,
+      offsetTop = 0,
+      offsetLeft = 0,
+      scale = 0,
+    } = vp
+
+    setWindowSize((prevState) => {
+      if (
+        width === prevState.width &&
+        height === prevState.height &&
+        offsetTop === prevState.offsetTop &&
+        offsetLeft === prevState.offsetLeft &&
+        scale === prevState.scale
+      ) {
+        return prevState
+      }
+
+      return { width, height, offsetTop, offsetLeft, scale }
+    })
+  }, { wait: 200 })
+
+  useEffect(() => {
+    const visualViewport = window.visualViewport
+    if (!visualViewport) return
+
+    visualViewport.addEventListener("resize", handleViewportChange)
+
+    handleViewportChange()
+
+    return () => {
+      visualViewport.removeEventListener("resize", handleViewportChange)
+    }
+  }, [handleViewportChange])
+
+  return windowSize
+}