@allbluecn/web-app 0.6.3 → 0.7.1

package/src/components/tiptap/node/toc-node/context/toc-context.tsx

@@ -0,0 +1,214 @@
+// 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 {
+  createContext,
+  useContext,
+  useState,
+  useCallback,
+  type ReactNode,
+} from "react"
+import type {
+  TableOfContentData,
+  TableOfContentDataItem,
+} from "@tiptap/extension-table-of-contents"
+import { selectNodeAndHideFloating } from "../../../hooks/use-floating-toolbar-visibility.ts"
+
+type TocState = {
+  tocContent: TableOfContentData | null
+  setTocContent: (value: TableOfContentData | null) => void
+
+  navigateToHeading: (
+    item: TableOfContentDataItem,
+    options?: {
+      topOffset?: number
+      behavior?: ScrollBehavior
+    }
+  ) => void
+
+  normalizeHeadingDepths: <
+    T extends { level?: number; originalLevel?: number },
+  >(
+    headingList: T[]
+  ) => number[]
+}
+
+const TocContext = createContext<TocState | undefined>(undefined)
+
+/**
+ * Normalizes heading depths for a table of contents (TOC) structure.
+ *
+ * This function ensures proper hierarchical nesting where a heading can only be
+ * a child of a previous heading with a smaller level number (higher priority).
+ * It prevents incorrect structures like h2 being listed under h3.
+ *
+ * Algorithm:
+ * 1. Rebases all levels so the minimum level becomes 1 (root level)
+ * 2. Maintains a stack of ancestors; pops entries until a smaller level is found
+ * 3. If found, nests it under that parent (parent depth + 1)
+ * 4. If not found, treats it as a root-level item (depth = 1)
+ *
+ * @param items - Array of heading items with `level` or `originalLevel` properties
+ * @returns Array of normalized depths corresponding to each heading item
+ */
+export function normalizeHeadingDepths<
+  T extends { level?: number; originalLevel?: number },
+>(items: T[]): number[] {
+  if (items.length === 0) return []
+
+  const raw = items.map((h) => h.originalLevel ?? h.level ?? 1)
+
+  const positives = raw.filter((l) => l > 0)
+  const root = positives.includes(1) ? 1 : Math.min(...positives)
+
+  const lvl = raw.map((l) => Math.max(1, l - (root - 1)))
+
+  const depths: number[] = []
+  const stack: { level: number; depth: number }[] = []
+
+  for (let i = 0; i < lvl.length; i++) {
+    const currentLevel = lvl[i] ?? 1
+
+    // Pop until we find a valid parent (strictly smaller level)
+    while (stack.length > 0 && stack[stack.length - 1]!.level >= currentLevel) {
+      stack.pop()
+    }
+
+    const depth = stack.length === 0 ? 1 : stack[stack.length - 1]!.depth + 1
+
+    depths.push(depth)
+
+    stack.push({ level: currentLevel, depth })
+  }
+
+  return depths
+}
+
+/**
+ * Find the nearest scrollable ancestor of an element.
+ * Falls back to `window` when no scrollable container is found.
+ */
+export const getScrollableAncestor = (
+  element: HTMLElement
+): HTMLElement | Window => {
+  let parent = element.parentElement
+
+  while (parent) {
+    const { overflowY } = getComputedStyle(parent)
+
+    if (
+      (overflowY === "auto" || overflowY === "scroll") &&
+      parent.scrollHeight > parent.clientHeight
+    ) {
+      return parent
+    }
+
+    parent = parent.parentElement
+  }
+
+  return window
+}
+
+/**
+ * Check if an element is visible in the viewport (or scrollable container)
+ */
+const isElementVisible = (element: HTMLElement, topOffset: number): boolean => {
+  const rect = element.getBoundingClientRect()
+  const viewportHeight =
+    window.innerHeight || document.documentElement.clientHeight
+
+  // Element is visible if:
+  // - Its top is below the topOffset
+  // - Its bottom is above the viewport top
+  // - Its top is above the viewport bottom
+  return (
+    rect.top >= topOffset &&
+    rect.bottom > topOffset &&
+    rect.top < viewportHeight
+  )
+}
+
+/**
+ * Low-level navigate helper (not exported in context directly)
+ */
+const doNavigateToHeading = (
+  item: TableOfContentDataItem,
+  topOffset: number,
+  behavior: ScrollBehavior = "smooth"
+) => {
+  if (!item.dom || typeof window === "undefined") return
+
+  // Only scroll if element is not already visible
+  if (!isElementVisible(item.dom, topOffset)) {
+    const scroller = getScrollableAncestor(item.dom)
+
+    if (scroller instanceof Window) {
+      const rect = item.dom.getBoundingClientRect()
+      const top = rect.top + window.scrollY - topOffset
+      window.scrollTo({ top, behavior })
+    } else {
+      const rect = item.dom.getBoundingClientRect()
+      const containerRect = scroller.getBoundingClientRect()
+      const top = rect.top - containerRect.top + scroller.scrollTop - topOffset
+      scroller.scrollTo({ top, behavior })
+    }
+  }
+
+  if (item.editor && typeof item.pos === "number") {
+    selectNodeAndHideFloating(item.editor, item.pos)
+  }
+
+  if (item.id) {
+    const url = new URL(window.location.href)
+    url.hash = item.id
+    window.history.replaceState(null, "", url.toString())
+  }
+}
+
+export const TocProvider = ({ children }: { children: ReactNode }) => {
+  const [tocContent, setTocContent] = useState<TableOfContentData | null>(null)
+
+  const navigateToHeading = useCallback<TocState["navigateToHeading"]>(
+    (item, options) => {
+      const topOffset = options?.topOffset ?? 0
+      const behavior = options?.behavior ?? "smooth"
+      doNavigateToHeading(item, topOffset, behavior)
+    },
+    []
+  )
+
+  return (
+    <TocContext.Provider
+      value={{
+        tocContent,
+        setTocContent,
+        navigateToHeading,
+        normalizeHeadingDepths,
+      }}
+    >
+      {children}
+    </TocContext.Provider>
+  )
+}
+
+export const useToc = () => {
+  const ctx = useContext(TocContext)
+  if (!ctx) {
+    throw new Error("useToc must be used inside <TocProvider>")
+  }
+  return ctx
+}

package/src/components/tiptap/node/toc-node/extensions/toc-node-extension.ts

@@ -0,0 +1,172 @@
+// 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 { Node, mergeAttributes } from "@tiptap/core"
+import { ReactNodeViewRenderer } from "@tiptap/react"
+import { TocNodeComponent } from "../toc-node.tsx"
+
+export interface TocNodeAttrs {
+  /**
+   * The maximum number of headings to show in the TOC node.
+   * @default 20
+   */
+  maxShowCount?: number | null
+  /**
+   * Offset from the top of the viewport when scrolling to a heading.
+   * @default 0
+   */
+  topOffset?: number | null
+  /**
+   * Whether to show the "Table of contents" title.
+   * @default true
+   */
+  showTitle?: boolean | null
+}
+
+export interface TocNodeOptions extends TocNodeAttrs {
+  /**
+   * HTML attributes to add to the TOC node element
+   * @default {}
+   * @example { class: 'foo' }
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  HTMLAttributes: Record<string, any>
+}
+
+declare module "@tiptap/core" {
+  interface Commands<ReturnType> {
+    tocNode: {
+      /**
+       * Insert a table of contents node.
+       *
+       * Example:
+       * editor.commands.insertTocNode({ maxShowCount: 10 })
+       */
+      insertTocNode: (attrs?: TocNodeAttrs) => ReturnType
+    }
+  }
+}
+
+/**
+ * A Tiptap node extension that creates a table of contents node.
+ * @see registry/tiptap-node/toc-node/toc-node-component
+ */
+export const TocNode = Node.create<TocNodeOptions>({
+  name: "tocNode",
+
+  group: "block customNode",
+
+  draggable: true,
+
+  selectable: true,
+
+  atom: true,
+
+  addOptions() {
+    return {
+      topOffset: 0,
+      maxShowCount: 20,
+      showTitle: true,
+      HTMLAttributes: {},
+    }
+  },
+
+  addAttributes() {
+    return {
+      topOffset: {
+        default: null as number | null,
+        parseHTML: (element: HTMLElement) => {
+          const val = element.getAttribute("data-top-offset")
+          const num = val != null ? Number(val) : null
+          return Number.isFinite(num) ? num : null
+        },
+        renderHTML: (attrs: TocNodeAttrs) => {
+          if (attrs.topOffset == null) return {}
+          return { "data-top-offset": attrs.topOffset }
+        },
+      },
+      maxShowCount: {
+        default: null as number | null,
+        parseHTML: (element: HTMLElement) => {
+          const val = element.getAttribute("data-max-show-count")
+          const num = val != null ? Number(val) : null
+          return Number.isFinite(num) ? num : null
+        },
+        renderHTML: (attrs: TocNodeAttrs) => {
+          if (attrs.maxShowCount == null) return {}
+          return { "data-max-show-count": attrs.maxShowCount }
+        },
+      },
+      showTitle: {
+        default: true,
+
+        parseHTML: (element: HTMLElement) => {
+          const val = element.getAttribute("data-show-title")
+          if (val === "false") return false
+          if (val === "true") return true
+          return null
+        },
+
+        renderHTML: (attrs: TocNodeAttrs) => {
+          if (attrs.showTitle == null) return {}
+          return { "data-show-title": String(attrs.showTitle) }
+        },
+      },
+    }
+  },
+
+  parseHTML() {
+    return [{ tag: 'div[data-type="toc-node"]' }]
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return [
+      "div",
+      mergeAttributes(this.options.HTMLAttributes, HTMLAttributes, {
+        "data-type": "toc-node",
+      }),
+    ]
+  },
+
+  addNodeView() {
+    return ReactNodeViewRenderer(TocNodeComponent, {
+      stopEvent: ({ event }) => {
+        if (!(event instanceof MouseEvent)) return false
+
+        const el = event.target as HTMLElement | null
+        if (!el) return false
+
+        return Boolean(el.closest(".tiptap-table-of-contents-item"))
+      },
+    })
+  },
+
+  addCommands() {
+    return {
+      insertTocNode:
+        (attrs) =>
+        ({ commands }) => {
+          return commands.insertContent({
+            type: this.name,
+            attrs,
+          })
+        },
+    }
+  },
+})
+
+export default TocNode

package/src/components/tiptap/node/toc-node/index.ts

@@ -0,0 +1,20 @@
+// 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 "./extensions/toc-node-extension"
+export * from "./ui/toc-sidebar"
+export * from "./ui/toc-show-title-button"

package/src/components/tiptap/node/toc-node/toc-node.scss

@@ -0,0 +1,105 @@
+.tiptap.ProseMirror {
+  .node-tocNode.ProseMirror-selectednode {
+    border-radius: var(--tt-radius-md);
+    background-color: var(--tt-selection-color);
+  }
+
+  a.tiptap-table-of-contents-item {
+    color: var(--tt-toc-node-text-color);
+    text-decoration: underline var(--tt-toc-node-underline-color);
+    text-underline-offset: 4px;
+  }
+}
+
+.tiptap-table-of-contents-node {
+  margin: 1.5rem 0;
+
+  // TOC spacing configuration
+  --toc-indent: 1.5rem; // Base spacing per level (24px)
+  --toc-depth-factor: 1; // Global multiplier
+
+  --tt-toc-node-text-color: var(--tt-gray-light-a-600);
+  --tt-toc-node-text-hover-color: var(--tt-gray-light-a-800);
+  --tt-toc-node-bg-hover-color: var(--tt-gray-light-a-100);
+  --tt-toc-node-underline-color: var(--tt-gray-light-a-300);
+  --tt-toc-node-underline-hover-color: var(--tt-gray-light-a-400);
+
+  .dark & {
+    --tt-toc-node-text-color: var(--tt-gray-dark-a-600);
+    --tt-toc-node-text-hover-color: var(--tt-gray-dark-a-800);
+    --tt-toc-node-bg-hover-color: var(--tt-gray-dark-a-100);
+    --tt-toc-node-underline-color: var(--tt-gray-dark-a-300);
+    --tt-toc-node-underline-hover-color: var(--tt-gray-dark-a-400);
+  }
+
+  .tiptap-table-of-contents-empty {
+    padding: 1rem;
+    text-align: center;
+    color: var(--tt-toc-node-text-color);
+    font-size: 0.875rem;
+  }
+
+  .tiptap-table-of-contents-title {
+    font-size: 0.75rem;
+    font-weight: 600;
+    color: var(--tt-toc-node-text-hover-color);
+    margin-bottom: 0.5rem;
+  }
+
+  .tiptap-table-of-contents-list {
+    margin: 0;
+    padding: 0;
+  }
+
+  .tiptap-table-of-contents-item {
+    display: flex;
+    align-items: center;
+    height: 1.875rem;
+    font-size: 0.875rem;
+    font-weight: 400;
+    border-radius: var(--tt-radius-xs);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    user-select: none;
+    cursor: pointer;
+
+    // Central calculation: Base * (Depth - 1) * Factor
+    padding-inline-start: calc(
+      var(--toc-indent) * (var(--toc-depth, 1) - 1) * var(--toc-depth-factor)
+    );
+
+    &:hover {
+      background-color: var(--tt-toc-node-bg-hover-color);
+    }
+
+    // Fallback mappings in case inline style is missing
+    &[data-depth="1"] {
+      --toc-depth: 1;
+    }
+    &[data-depth="2"] {
+      --toc-depth: 2;
+    }
+    &[data-depth="3"] {
+      --toc-depth: 3;
+    }
+    &[data-depth="4"] {
+      --toc-depth: 4;
+    }
+    &[data-depth="5"] {
+      --toc-depth: 5;
+    }
+    &[data-depth="6"] {
+      --toc-depth: 6;
+    }
+  }
+
+  // Context-specific variants (optional)
+  &.toc--dense {
+    --toc-depth-factor: 0.75;
+  }
+
+  &.toc--loose {
+    --toc-depth-factor: 1.25;
+  }
+}

package/src/components/tiptap/node/toc-node/toc-node.tsx

@@ -0,0 +1,131 @@
+// 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, useMemo } from "react"
+import { useTranslation } from 'react-i18next'
+import { NodeViewWrapper } from "@tiptap/react"
+import type { NodeViewProps } from "@tiptap/react"
+import type {
+  TableOfContentData,
+  TableOfContentDataItem,
+} from "@tiptap/extension-table-of-contents"
+
+import { useToc } from "./context/toc-context.tsx"
+
+import "./toc-node.scss"
+
+type TocTreeNode = {
+  item: TableOfContentDataItem
+  depth: number
+}
+
+export function TocNodeComponent(props: NodeViewProps) {
+  const { t } = useTranslation('editor')
+  const { node, extension } = props
+  const { tocContent, navigateToHeading, normalizeHeadingDepths } = useToc()
+
+  const {
+    topOffset: optionTopOffset = 0,
+    maxShowCount: optionMaxShowCount = 20,
+    showTitle: optionShowTitle = true,
+  } = extension.options
+
+  const attrs = node.attrs ?? {}
+  const { backgroundColor } = attrs
+  const topOffset = attrs.topOffset ?? optionTopOffset
+  const maxShowCount = attrs.maxShowCount ?? optionMaxShowCount
+  const showTitle = attrs.showTitle ?? optionShowTitle
+
+  const headingList = useMemo<TableOfContentData>(
+    () => tocContent ?? [],
+    [tocContent]
+  )
+
+  const visibleHeadings = useMemo(
+    () => headingList.slice(0, maxShowCount),
+    [headingList, maxShowCount]
+  )
+
+  const normalizedDepths = useMemo<number[]>(
+    () => normalizeHeadingDepths(visibleHeadings),
+    [visibleHeadings, normalizeHeadingDepths]
+  )
+
+  const flatTocList = useMemo<TocTreeNode[]>(() => {
+    return visibleHeadings.map((item, index) => ({
+      item,
+      depth: normalizedDepths[index] ?? 1,
+    }))
+  }, [visibleHeadings, normalizedDepths])
+
+  const handleContentClick = useCallback(
+    (e: React.MouseEvent, item: TableOfContentDataItem) => {
+      e.preventDefault()
+      e.stopPropagation()
+      navigateToHeading(item, { topOffset })
+    },
+    [navigateToHeading, topOffset]
+  )
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { style: _, ...HTMLAttributes } = props.HTMLAttributes
+
+  const wrapperProps = {
+    className: "tiptap-table-of-contents-node",
+    style: { backgroundColor: backgroundColor || undefined },
+    ...HTMLAttributes,
+  }
+
+  if (!visibleHeadings.length) {
+    return (
+      <NodeViewWrapper {...wrapperProps}>
+        <div className="tiptap-table-of-contents-empty">
+          Add headings to create a table of contents.
+        </div>
+      </NodeViewWrapper>
+    )
+  }
+
+  return (
+    <NodeViewWrapper {...wrapperProps}>
+      {showTitle && (
+        <div className="tiptap-table-of-contents-title">Table of contents</div>
+      )}
+      <nav
+        aria-label={t('table-of-contents')}
+        className="tiptap-table-of-contents-list"
+      >
+        {flatTocList.map((node, index) => (
+          <a
+            key={node.item.id ?? `${index}-${node.item.textContent}`}
+            href={`#${node.item.id}`}
+            rel="noopener noreferrer"
+            className="tiptap-table-of-contents-item notranslate"
+            data-depth={node.depth}
+            style={{ "--toc-depth": node.depth } as React.CSSProperties}
+            onClick={(e) => handleContentClick(e, node.item)}
+          >
+            {node.item.textContent}
+          </a>
+        ))}
+      </nav>
+    </NodeViewWrapper>
+  )
+}
+
+export default TocNodeComponent

package/src/components/tiptap/node/toc-node/ui/toc-show-title-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 "./toc-show-title"
+export * from "./toc-show-title-button"