@brett_lamy/docstream-editor 0.3.7 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brett_lamy/docstream-editor",
-  "version": "0.3.7",
+  "version": "0.5.1",
   "description": "TipTap editor for Docstream GitBook-style markdown documents.",
   "type": "module",
   "scripts": {
@@ -11,6 +11,7 @@
   "types": "./src/index.ts",
   "files": [
     "src",
+    "!src/**/*.test.ts",
     "README.md"
   ],
   "sideEffects": [
@@ -32,7 +33,7 @@
     "./styles.css": "./src/styles.css"
   },
   "dependencies": {
-    "@brett_lamy/docstream": "0.4.0",
+    "@brett_lamy/docstream": "0.5.1",
     "lowlight": "^3.3.0",
     "lucide-react": "^1.17.0"
   },

package/src/editor/Editor.tsx

@@ -10,7 +10,7 @@ import {
   Strikethrough,
 } from "lucide-react"
 
-import { parseMarkdown, serializeMarkdown } from "@brett_lamy/docstream/gitbook"
+import { parseMarkdown, serializeMarkdown, type CitationDef } from "@brett_lamy/docstream/gitbook"
 import { astToTiptap, tiptapToAst, type PMNode } from "./convert"
 import { createGitbookExtensions } from "./extensions"
 import type { SlashItem } from "./slash-menu"
@@ -24,6 +24,8 @@ export interface GitbookEditorProps {
   toolbar?: boolean
   /** Built-in "/" slash menu: true (default), false, or a custom item list. */
   slashMenu?: boolean | { items?: SlashItem[] }
+  /** The "@" / "#" reference chip pickers: true (default), false, or known id lists. */
+  references?: boolean | { mentions?: string[]; tags?: string[] }
   /** Whether the document is editable (default true). */
   editable?: boolean
   /** Placeholder shown in an empty document. */
@@ -112,6 +114,7 @@ export function GitbookEditor({
   onChange,
   toolbar = true,
   slashMenu = true,
+  references = true,
   editable = true,
   placeholder,
   className,
@@ -125,14 +128,24 @@ export function GitbookEditor({
   // Tracks the markdown the editor itself produced, so external updates
   // (file switches) reset content but our own onChange echoes don't.
   const lastEmitted = useRef<string | null>(null)
+  // PM JSON has nowhere to carry doc-level citation definitions; remember the
+  // ones from the last applied markdown and reattach them on serialize.
+  const citationsRef = useRef<CitationDef[] | undefined>(undefined)
   const controlled = markdown !== undefined
 
+  const parseAndTrack = (md: string) => {
+    const doc = parseMarkdown(md)
+    citationsRef.current = doc.citations
+    return doc
+  }
+
   const editor = useEditor({
     editable,
     autofocus,
     extensions: createGitbookExtensions({
       ...(placeholder !== undefined ? { placeholder } : {}),
       slashMenu,
+      references,
       ...(disableHistory !== undefined ? { disableHistory } : {}),
       ...(extensions ? { extensions } : {}),
     }),
@@ -140,10 +153,12 @@ export function GitbookEditor({
       handleKeyDown: (_view, event) => onKeyDown?.(event) ?? false,
       handlePaste: (_view, event) => onPaste?.(event) ?? false,
     },
-    ...(controlled ? { content: astToTiptap(parseMarkdown(markdown as string)) } : {}),
+    ...(controlled ? { content: astToTiptap(parseAndTrack(markdown as string)) } : {}),
     onUpdate({ editor }) {
       if (!onChange) return
-      const md = serializeMarkdown(tiptapToAst(editor.getJSON() as PMNode))
+      const ast = tiptapToAst(editor.getJSON() as PMNode)
+      if (citationsRef.current?.length) ast.citations = citationsRef.current
+      const md = serializeMarkdown(ast)
       lastEmitted.current = md
       onChange(md)
     },
@@ -159,7 +174,9 @@ export function GitbookEditor({
     if (!editor || !controlled) return
     if (markdown === lastEmitted.current) return
     lastEmitted.current = markdown as string
-    editor.commands.setContent(astToTiptap(parseMarkdown(markdown as string)), { emitUpdate: false })
+    const doc = parseMarkdown(markdown as string)
+    citationsRef.current = doc.citations
+    editor.commands.setContent(astToTiptap(doc), { emitUpdate: false })
   }, [editor, controlled, markdown])
 
   if (!editor) return null

package/src/editor/convert.ts

@@ -13,8 +13,16 @@ export interface PMNode {
 
 function inlineToPM(nodes: Inline[]): PMNode[] {
   return nodes
-    .filter((n) => n.type === "image" || n.text.length > 0)
+    // Only empty text nodes are dropped — every non-text inline must pass, or
+    // it silently vanishes on the first edit round-trip.
+    .filter((n) => n.type !== "text" || n.text.length > 0)
     .map((n) => {
+      if (n.type === "reference") {
+        return {
+          type: "gbReference",
+          attrs: { kind: n.kind, id: n.id, url: n.url ?? "", label: n.label ?? "" },
+        }
+      }
       if (n.type === "image") {
         return {
           type: "gbInlineImage",
@@ -191,8 +199,19 @@ export function astToTiptap(doc: DocumentNode): PMNode {
 function pmTextToInline(nodes: PMNode[] | undefined): Inline[] {
   if (!nodes) return []
   return nodes
-    .filter((n) => (n.type === "text" && n.text) || n.type === "gbInlineImage")
+    .filter((n) => (n.type === "text" && n.text) || n.type === "gbInlineImage" || n.type === "gbReference")
     .map((n): Inline => {
+      if (n.type === "gbReference") {
+        const a = n.attrs ?? {}
+        const kind = a.kind === "tag" ? "tag" : a.kind === "citation" ? "citation" : "mention"
+        return {
+          type: "reference",
+          kind,
+          id: String(a.id ?? ""),
+          ...(a.url ? { url: String(a.url) } : {}),
+          ...(a.label ? { label: String(a.label) } : {}),
+        }
+      }
       if (n.type === "gbInlineImage") {
         const a = n.attrs ?? {}
         return {

package/src/editor/extensions.ts

@@ -6,6 +6,7 @@ import { getSchema, type AnyExtension } from "@tiptap/core"
 import type { Schema } from "@tiptap/pm/model"
 import { GbCodeBlock, gitbookNodes } from "./nodes"
 import { SlashMenu, createSlashMenu, type SlashItem } from "./slash-menu"
+import { createReferenceSuggestion } from "./reference-menu"
 
 // Carries GitBook's data-view (e.g. "cards") through the editor untouched.
 export const GbTable = Table.extend({
@@ -18,6 +19,11 @@ export interface GitbookExtensionOptions {
   placeholder?: string
   /** Built-in "/" slash menu: true (default), false, or a custom item list. */
   slashMenu?: boolean | { items?: SlashItem[] }
+  /**
+   * The "@" / "#" reference chip pickers: true (default), false, or lists of
+   * known ids to offer. Free-form entry always works.
+   */
+  references?: boolean | { mentions?: string[]; tags?: string[] }
   /**
    * Disable StarterKit's built-in undo/redo. Required when wiring Yjs
    * Collaboration, which provides its own shared history.
@@ -36,6 +42,7 @@ export function createGitbookExtensions(options: GitbookExtensionOptions = {}):
   const {
     placeholder = "Write, or type / to insert a block…",
     slashMenu = true,
+    references = true,
     disableHistory = false,
     extensions = [],
   } = options
@@ -60,6 +67,14 @@ export function createGitbookExtensions(options: GitbookExtensionOptions = {}):
     list.push(slashMenu === true ? SlashMenu : createSlashMenu(slashMenu.items))
   }
 
+  if (references) {
+    const opts = references === true ? {} : references
+    list.push(
+      createReferenceSuggestion({ char: "@", ...(opts.mentions ? { items: opts.mentions } : {}) }),
+      createReferenceSuggestion({ char: "#", ...(opts.tags ? { items: opts.tags } : {}) })
+    )
+  }
+
   list.push(...extensions)
   return list
 }

package/src/editor/nodes.tsx

@@ -9,8 +9,10 @@ import {
 } from "@tiptap/react"
 import {
   AlertTriangle,
+  AtSign,
   CheckCircle2,
   ChevronDown,
+  Hash,
   Info,
   Link2,
   FileCode2,
@@ -711,6 +713,56 @@ export const GbInlineImage = Node.create({
   },
 })
 
+// ---------- Reference chips (@mention, #tag, [^n] citation) ----------
+
+function ReferenceView({ node }: NodeViewProps) {
+  const { kind, id, url, label } = node.attrs
+  return (
+    <NodeViewWrapper as="span" className="gb-ref-wrap" contentEditable={false}>
+      {kind === "citation" ? (
+        <span className="gb-cite" title={label || url || undefined}>
+          {id}
+        </span>
+      ) : (
+        <span className={`gb-ref gb-ref-${kind}`}>
+          {kind === "mention" ? <AtSign className="gb-ref-icon" /> : <Hash className="gb-ref-icon" />}
+          {id}
+        </span>
+      )}
+    </NodeViewWrapper>
+  )
+}
+
+export const GbReference = Node.create({
+  name: "gbReference",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      kind: { default: "mention" },
+      id: { default: "" },
+      url: { default: "" },
+      label: { default: "" },
+    }
+  },
+  parseHTML() {
+    return [{ tag: "span[data-gb-ref]" }]
+  },
+  renderHTML({ HTMLAttributes, node }) {
+    const sigil = node.attrs.kind === "mention" ? "@" : node.attrs.kind === "tag" ? "#" : "^"
+    return [
+      "span",
+      mergeAttributes(HTMLAttributes, { "data-gb-ref": node.attrs.kind, "data-gb-ref-id": node.attrs.id }),
+      `${sigil}${node.attrs.id}`,
+    ]
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ReferenceView)
+  },
+})
+
 // ---------- Updates (changelog) ----------
 
 export const GbUpdates = Node.create({
@@ -849,4 +901,5 @@ export const gitbookNodes = [
   GbUpdate,
   GbOpenapi,
   GbInlineImage,
+  GbReference,
 ]

package/src/editor/reference-menu.tsx

@@ -0,0 +1,68 @@
+import { Extension, type Editor, type Range } from "@tiptap/core"
+import Suggestion from "@tiptap/suggestion"
+import { PluginKey } from "@tiptap/pm/state"
+import { AtSign, Hash } from "lucide-react"
+
+import { createSuggestionRender, type SuggestionMenuItem } from "./suggestion-menu"
+
+export type ReferenceTrigger = "@" | "#"
+
+interface ReferenceItem extends SuggestionMenuItem {
+  id: string
+}
+
+export interface ReferenceSuggestionOptions {
+  char: ReferenceTrigger
+  /** Known ids offered in the picker; free-form entry always works. */
+  items?: string[]
+}
+
+const KIND: Record<ReferenceTrigger, "mention" | "tag"> = { "@": "mention", "#": "tag" }
+
+/**
+ * An `@mention` / `#tag` picker built on @tiptap/suggestion. Filters the host's
+ * known ids and always offers inserting the raw query, so typing `@anything⏎`
+ * works with no list configured.
+ */
+export function createReferenceSuggestion({ char, items = [] }: ReferenceSuggestionOptions) {
+  const kind = KIND[char]
+  const icon = char === "@" ? AtSign : Hash
+  return Extension.create({
+    name: `${kind}Suggestion`,
+    addProseMirrorPlugins() {
+      return [
+        Suggestion<ReferenceItem>({
+          editor: this.editor,
+          char,
+          startOfLine: false,
+          allowSpaces: false,
+          // Each Suggestion plugin needs its own key — the default is shared
+          // with the slash menu and would collide.
+          pluginKey: new PluginKey(`${kind}Suggestion`),
+          items: ({ query }) => {
+            const q = query.toLowerCase()
+            const matches = items
+              .filter((id) => id.toLowerCase().includes(q))
+              .map((id) => ({ id, title: `${char}${id}`, icon }))
+            const freeForm = query && !items.some((id) => id.toLowerCase() === q)
+            return freeForm ? [...matches, { id: query, title: `${char}${query}`, icon }] : matches
+          },
+          command: ({ editor, range, props }) => {
+            ;(editor as Editor)
+              .chain()
+              .focus()
+              .deleteRange(range as Range)
+              .insertContent([
+                { type: "gbReference", attrs: { kind, id: props.id } },
+                { type: "text", text: " " },
+              ])
+              .run()
+          },
+          render: createSuggestionRender<ReferenceItem>(
+            char === "@" ? "Type a name to mention" : "Type a tag"
+          ),
+        }),
+      ]
+    },
+  })
+}

package/src/editor/slash-menu.tsx

@@ -1,14 +1,5 @@
-import {
-  forwardRef,
-  useEffect,
-  useImperativeHandle,
-  useLayoutEffect,
-  useRef,
-  useState,
-} from "react"
 import { Extension, type Editor, type Range } from "@tiptap/core"
-import Suggestion, { type SuggestionProps } from "@tiptap/suggestion"
-import { ReactRenderer } from "@tiptap/react"
+import Suggestion from "@tiptap/suggestion"
 import {
   Columns2,
   FileCode2,
@@ -29,6 +20,7 @@ import {
   Quote,
   Sigma,
   SquareChevronDown,
+  Superscript,
   Table as TableIcon,
   Webhook,
   Workflow,
@@ -36,6 +28,7 @@ import {
 } from "lucide-react"
 
 import type { PMNode } from "./convert"
+import { createSuggestionRender } from "./suggestion-menu"
 
 const para = (text = ""): PMNode =>
   text ? { type: "paragraph", content: [{ type: "text", text }] } : { type: "paragraph" }
@@ -176,106 +169,26 @@ export const SLASH_ITEMS: SlashItem[] = [
       content: [{ type: "text", text: "graph TD\n  A --> B" }],
     }),
   },
-]
-
-interface MenuProps {
-  items: SlashItem[]
-  command: (item: SlashItem) => void
-  clientRect: (() => DOMRect | null) | null
-}
-
-interface MenuHandle {
-  onKeyDown: (event: KeyboardEvent) => boolean
-}
-
-const SlashMenuView = forwardRef<MenuHandle, MenuProps>(function SlashMenuView(
-  { items, command, clientRect },
-  ref
-) {
-  const [index, setIndex] = useState(0)
-  const itemRefs = useRef<Array<HTMLButtonElement | null>>([])
-
-  useEffect(() => setIndex(0), [items])
-
-  // Keep the active item visible while arrowing through a long list.
-  useEffect(() => {
-    itemRefs.current[index]?.scrollIntoView({ block: "nearest" })
-  }, [index])
-
-  useImperativeHandle(ref, () => ({
-    onKeyDown(event) {
-      if (event.key === "ArrowDown") {
-        setIndex((i) => (i + 1) % Math.max(items.length, 1))
-        return true
-      }
-      if (event.key === "ArrowUp") {
-        setIndex((i) => (i - 1 + items.length) % Math.max(items.length, 1))
-        return true
-      }
-      if (event.key === "Enter") {
-        if (items[index]) command(items[index])
-        return true
-      }
-      return false
+  {
+    title: "Citation",
+    keywords: "cite footnote source reference superscript",
+    icon: Superscript,
+    run: (e) => {
+      // Next free numeric citation id in the document.
+      let max = 0
+      e.state.doc.descendants((node) => {
+        if (node.type.name === "gbReference" && node.attrs.kind === "citation") {
+          const n = Number(node.attrs.id)
+          if (Number.isInteger(n) && n > max) max = n
+        }
+      })
+      e.chain()
+        .focus()
+        .insertContent([{ type: "gbReference", attrs: { kind: "citation", id: String(max + 1) } }])
+        .run()
     },
-  }))
-
-  const menuRef = useRef<HTMLDivElement>(null)
-  const rect = clientRect?.()
-  const [pos, setPos] = useState<{ left: number; top: number }>(() => ({
-    left: rect ? rect.left : 0,
-    top: rect ? rect.bottom + 6 : 0,
-  }))
-
-  // Position below the cursor, but flip above when there isn't room below
-  // (e.g. triggered near the bottom of the viewport). Measured after render.
-  useLayoutEffect(() => {
-    const r = clientRect?.()
-    const el = menuRef.current
-    if (!r || !el) return
-    const margin = 6
-    const menuH = el.offsetHeight
-    const menuW = el.offsetWidth
-    const spaceBelow = window.innerHeight - r.bottom
-    let top = r.bottom + margin
-    if (spaceBelow < menuH + margin && r.top - margin > menuH) {
-      top = r.top - menuH - margin
-    }
-    top = Math.max(margin, Math.min(top, window.innerHeight - menuH - margin))
-    let left = Math.min(r.left, window.innerWidth - menuW - margin)
-    left = Math.max(margin, left)
-    if (left !== pos.left || top !== pos.top) setPos({ left, top })
-  }, [clientRect, items, pos.left, pos.top])
-
-  if (!rect) return null
-
-  return (
-    <div
-      ref={menuRef}
-      className="slash-menu"
-      style={{ position: "fixed", left: pos.left, top: pos.top }}
-    >
-      {items.length === 0 && <div className="slash-empty">No matching blocks</div>}
-      {items.map((item, i) => (
-        <button
-          key={item.title}
-          ref={(el) => {
-            itemRefs.current[i] = el
-          }}
-          className={`slash-item ${i === index ? "slash-item-active" : ""}`}
-          onMouseEnter={() => setIndex(i)}
-          onMouseDown={(e) => {
-            e.preventDefault()
-            command(item)
-          }}
-        >
-          <item.icon className="size-4" />
-          <span>{item.title}</span>
-        </button>
-      ))}
-    </div>
-  )
-})
+  },
+]
 
 export type { SlashItem }
 
@@ -287,7 +200,6 @@ export function createSlashMenu(items: SlashItem[] = SLASH_ITEMS) {
   return Extension.create({
     name: "slashMenu",
     addProseMirrorPlugins() {
-      let renderer: ReactRenderer<MenuHandle, MenuProps> | null = null
       return [
         Suggestion<SlashItem>({
           editor: this.editor,
@@ -297,44 +209,11 @@ export function createSlashMenu(items: SlashItem[] = SLASH_ITEMS) {
             items.filter((item) =>
               `${item.title} ${item.keywords}`.toLowerCase().includes(query.toLowerCase())
             ),
-        command: ({ editor, range, props }) => {
-          editor.chain().focus().deleteRange(range as Range).run()
-          props.run(editor as Editor)
-        },
-        render: () => ({
-          onStart: (props: SuggestionProps<SlashItem>) => {
-            renderer = new ReactRenderer(SlashMenuView, {
-              editor: props.editor,
-              props: {
-                items: props.items,
-                command: props.command,
-                clientRect: props.clientRect ?? null,
-              },
-            })
-            document.body.appendChild(renderer.element)
-          },
-          onUpdate: (props: SuggestionProps<SlashItem>) => {
-            renderer?.updateProps({
-              items: props.items,
-              command: props.command,
-              clientRect: props.clientRect ?? null,
-            })
-          },
-          onKeyDown: ({ event }) => {
-            if (event.key === "Escape") {
-              renderer?.destroy()
-              renderer?.element.remove()
-              renderer = null
-              return true
-            }
-            return renderer?.ref?.onKeyDown(event) ?? false
-          },
-          onExit: () => {
-            renderer?.element.remove()
-            renderer?.destroy()
-            renderer = null
+          command: ({ editor, range, props }) => {
+            editor.chain().focus().deleteRange(range as Range).run()
+            props.run(editor as Editor)
           },
-          }),
+          render: createSuggestionRender<SlashItem>("No matching blocks"),
         }),
       ]
     },

package/src/editor/suggestion-menu.tsx

@@ -0,0 +1,164 @@
+import {
+  forwardRef,
+  useEffect,
+  useImperativeHandle,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ForwardRefExoticComponent,
+  type RefAttributes,
+} from "react"
+import type { SuggestionProps } from "@tiptap/suggestion"
+import { ReactRenderer } from "@tiptap/react"
+import type { LucideIcon } from "lucide-react"
+
+// Shared popup used by the "/" slash menu and the "@"/"#" reference menus.
+
+export interface SuggestionMenuItem {
+  title: string
+  icon: LucideIcon
+}
+
+export interface MenuProps<Item extends SuggestionMenuItem> {
+  items: Item[]
+  command: (item: Item) => void
+  clientRect: (() => DOMRect | null) | null
+  emptyLabel?: string
+}
+
+export interface MenuHandle {
+  onKeyDown: (event: KeyboardEvent) => boolean
+}
+
+export const SuggestionMenuView = forwardRef<MenuHandle, MenuProps<SuggestionMenuItem>>(
+  function SuggestionMenuView({ items, command, clientRect, emptyLabel = "No matches" }, ref) {
+    const [index, setIndex] = useState(0)
+    const itemRefs = useRef<Array<HTMLButtonElement | null>>([])
+
+    useEffect(() => setIndex(0), [items])
+
+    // Keep the active item visible while arrowing through a long list.
+    useEffect(() => {
+      itemRefs.current[index]?.scrollIntoView({ block: "nearest" })
+    }, [index])
+
+    useImperativeHandle(ref, () => ({
+      onKeyDown(event) {
+        if (event.key === "ArrowDown") {
+          setIndex((i) => (i + 1) % Math.max(items.length, 1))
+          return true
+        }
+        if (event.key === "ArrowUp") {
+          setIndex((i) => (i - 1 + items.length) % Math.max(items.length, 1))
+          return true
+        }
+        if (event.key === "Enter") {
+          if (items[index]) command(items[index])
+          return true
+        }
+        return false
+      },
+    }))
+
+    const menuRef = useRef<HTMLDivElement>(null)
+    const rect = clientRect?.()
+    const [pos, setPos] = useState<{ left: number; top: number }>(() => ({
+      left: rect ? rect.left : 0,
+      top: rect ? rect.bottom + 6 : 0,
+    }))
+
+    // Position below the cursor, but flip above when there isn't room below
+    // (e.g. triggered near the bottom of the viewport). Measured after render.
+    useLayoutEffect(() => {
+      const r = clientRect?.()
+      const el = menuRef.current
+      if (!r || !el) return
+      const margin = 6
+      const menuH = el.offsetHeight
+      const menuW = el.offsetWidth
+      const spaceBelow = window.innerHeight - r.bottom
+      let top = r.bottom + margin
+      if (spaceBelow < menuH + margin && r.top - margin > menuH) {
+        top = r.top - menuH - margin
+      }
+      top = Math.max(margin, Math.min(top, window.innerHeight - menuH - margin))
+      let left = Math.min(r.left, window.innerWidth - menuW - margin)
+      left = Math.max(margin, left)
+      if (left !== pos.left || top !== pos.top) setPos({ left, top })
+    }, [clientRect, items, pos.left, pos.top])
+
+    if (!rect) return null
+
+    return (
+      <div
+        ref={menuRef}
+        className="slash-menu"
+        style={{ position: "fixed", left: pos.left, top: pos.top }}
+      >
+        {items.length === 0 && <div className="slash-empty">{emptyLabel}</div>}
+        {items.map((item, i) => (
+          <button
+            key={item.title}
+            ref={(el) => {
+              itemRefs.current[i] = el
+            }}
+            className={`slash-item ${i === index ? "slash-item-active" : ""}`}
+            onMouseEnter={() => setIndex(i)}
+            onMouseDown={(e) => {
+              e.preventDefault()
+              command(item)
+            }}
+          >
+            <item.icon className="size-4" />
+            <span>{item.title}</span>
+          </button>
+        ))}
+      </div>
+    )
+  }
+)
+
+/**
+ * The Suggestion render lifecycle wired to SuggestionMenuView — shared by the
+ * slash menu and the reference menus.
+ */
+export function createSuggestionRender<Item extends SuggestionMenuItem>(emptyLabel?: string) {
+  // The view only reads SuggestionMenuItem fields, so retyping it per Item is safe.
+  const View = SuggestionMenuView as unknown as ForwardRefExoticComponent<
+    MenuProps<Item> & RefAttributes<MenuHandle>
+  >
+  let renderer: ReactRenderer<MenuHandle, MenuProps<Item>> | null = null
+  const menuProps = (props: SuggestionProps<Item>): MenuProps<Item> => ({
+    items: props.items,
+    command: props.command,
+    clientRect: props.clientRect ?? null,
+    ...(emptyLabel !== undefined ? { emptyLabel } : {}),
+  })
+  return () => ({
+    onStart: (props: SuggestionProps<Item>) => {
+      const r = new ReactRenderer(View, {
+        editor: props.editor,
+        props: menuProps(props),
+      })
+      renderer = r
+      document.body.appendChild(r.element)
+    },
+    onUpdate: (props: SuggestionProps<Item>) => {
+      renderer?.updateProps(menuProps(props))
+    },
+    onKeyDown: ({ event }: { event: KeyboardEvent }) => {
+      if (event.key === "Escape") {
+        renderer?.destroy()
+        renderer?.element.remove()
+        renderer = null
+        return true
+      }
+      return renderer?.ref?.onKeyDown(event) ?? false
+    },
+    onExit: () => {
+      renderer?.element.remove()
+      renderer?.destroy()
+      renderer = null
+    },
+  })
+}

package/src/index.ts

@@ -7,9 +7,13 @@ export type { PMNode } from "./editor/convert"
 // or a bespoke slash menu) instead of the batteries-included GitbookEditor.
 export { createGitbookExtensions, getGitbookSchema, GbTable } from "./editor/extensions"
 export type { GitbookExtensionOptions } from "./editor/extensions"
-export { gitbookNodes, GbCodeBlock } from "./editor/nodes"
+export { gitbookNodes, GbCodeBlock, GbReference } from "./editor/nodes"
 export { SlashMenu, createSlashMenu, SLASH_ITEMS } from "./editor/slash-menu"
 export type { SlashItem } from "./editor/slash-menu"
+export { createReferenceSuggestion } from "./editor/reference-menu"
+export type { ReferenceSuggestionOptions, ReferenceTrigger } from "./editor/reference-menu"
+export { SuggestionMenuView, createSuggestionRender } from "./editor/suggestion-menu"
+export type { SuggestionMenuItem } from "./editor/suggestion-menu"
 export { ReactDemoEditor } from "./editor/ReactDemoEditor"
 export type { ReactDemoEditorProps } from "./editor/ReactDemoEditor"
 export { SourceFileEditor } from "./editor/SourceFileEditor"

package/src/styles.css

@@ -739,3 +739,56 @@
   .gb-react-demo-files-header { flex: 0 0 auto; border-bottom: 0; }
   .gb-react-demo-file { width: auto; flex: 0 0 auto; }
 }
+
+/* ---- Inline reference chips (@mention, #tag) and citations ---- */
+
+.gb-ref-wrap {
+  display: inline;
+}
+
+.gb-ref {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  padding: 1px 8px;
+  border-radius: 999px;
+  font-size: 0.85em;
+  font-weight: 500;
+  line-height: 1.5;
+  vertical-align: baseline;
+}
+
+.gb-ref-icon {
+  width: 12px;
+  height: 12px;
+}
+
+.gb-ref-mention {
+  border: 1px solid rgba(59, 130, 246, 0.45);
+  background: rgba(59, 130, 246, 0.1);
+  color: var(--gb-info, #3b82f6);
+}
+
+.gb-ref-tag {
+  border: 1px solid var(--gb-border);
+  background: var(--gb-muted);
+  color: var(--gb-muted-foreground);
+}
+
+.gb-cite {
+  display: inline-block;
+  padding: 1px 5px;
+  border-radius: 5px;
+  background: rgba(59, 130, 246, 0.14);
+  color: var(--gb-info, #3b82f6);
+  font-size: 10px;
+  font-weight: 700;
+  line-height: 1.4;
+  vertical-align: super;
+}
+
+.ProseMirror-selectednode .gb-ref,
+.ProseMirror-selectednode .gb-cite {
+  outline: 2px solid var(--gb-primary);
+  outline-offset: 1px;
+}