@brett_lamy/docstream-editor 0.6.0 → 0.7.0

package/README.md

@@ -109,6 +109,29 @@ The editor supports common ProseMirror/TipTap content plus GitBook-flavored bloc
 
 Some blocks are intentionally represented as structured nodes rather than fully bespoke editing controls. They are preserved through parse, edit, and serialize flows so the document can continue to round-trip as GitBook-style markdown.
 
+## Mentions, channels, and codebases
+
+Typing `@`, `#`, or `$` opens a picker and inserts a reference chip that serializes as
+`@id`, `#id`, or `$id` (`$org/repo` works too). Feed each trigger a static list or an
+async `(query) => options` function; options can carry a `label`, `description`, and
+`group` (rendered as section headers). `$` is only enabled when `codebases` is set, so
+dollar signs in ordinary prose never open a menu. Free-form entry is always offered.
+
+```tsx
+<GitbookEditor
+  markdown={md}
+  onChange={setMd}
+  references={{
+    mentions: [
+      ...people.map((p) => ({ id: p.handle, label: p.name, description: p.email, group: "People" })),
+      ...agents.map((a) => ({ id: a.handle, label: a.name, description: a.harness, group: "Agents" })),
+    ],
+    tags: async (query) => searchChannels(query), // [{ id: "general", description: "channel" }]
+    codebases: async (query) => searchRepos(query), // [{ id: "reading-room" }]
+  }}
+/>
+```
+
 ## Edit a referenced source file
 
 `GitbookEditor` edits the Markdown composition, including a structured

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brett_lamy/docstream-editor",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "TipTap editor for Docstream GitBook-style markdown documents.",
   "type": "module",
   "scripts": {
@@ -33,7 +33,7 @@
     "./styles.css": "./src/styles.css"
   },
   "dependencies": {
-    "@brett_lamy/docstream": "0.5.7",
+    "@brett_lamy/docstream": "0.6.0",
     "gpu-lexer": "0.0.2",
     "lucide-react": "^1.17.0"
   },

package/src/editor/Editor.tsx

@@ -13,7 +13,7 @@ import {
 import { parseMarkdown, serializeMarkdown, type CitationDef } from "@brett_lamy/docstream/gitbook"
 import type { SourceFileSnapshot, SourceReferenceClient } from "@brett_lamy/docstream/source"
 import { astToTiptap, tiptapToAst, type PMNode } from "./convert"
-import { createGitbookExtensions } from "./extensions"
+import { createGitbookExtensions, type ReferenceSources } from "./extensions"
 import { EditorRuntimeProvider } from "./runtime"
 import type { SlashItem } from "./slash-menu"
 
@@ -26,8 +26,11 @@ 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[] }
+  /**
+   * Reference chip pickers: true (default "@"/"#"), false, or per-trigger sources —
+   * static lists or async `(query) => options`. A `codebases` source enables "$".
+   */
+  references?: boolean | ReferenceSources
   /** Whether the document is editable (default true). */
   editable?: boolean
   /** Placeholder shown in an empty document. */

package/src/editor/convert.ts

@@ -203,7 +203,8 @@ function pmTextToInline(nodes: PMNode[] | undefined): Inline[] {
     .map((n): Inline => {
       if (n.type === "gbReference") {
         const a = n.attrs ?? {}
-        const kind = a.kind === "tag" ? "tag" : a.kind === "citation" ? "citation" : "mention"
+        const kind =
+          a.kind === "tag" || a.kind === "codebase" || a.kind === "citation" ? a.kind : "mention"
         return {
           type: "reference",
           kind,

package/src/editor/extensions.ts

@@ -6,7 +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"
+import { createReferenceSuggestion, type ReferenceSource } from "./reference-menu"
 
 // Carries GitBook's data-view (e.g. "cards") through the editor untouched.
 export const GbTable = Table.extend({
@@ -15,15 +15,26 @@ export const GbTable = Table.extend({
   },
 })
 
+export interface ReferenceSources {
+  /** "@" — people, agents, … */
+  mentions?: ReferenceSource
+  /** "#" — channels, tags, … */
+  tags?: ReferenceSource
+  /** "$" — codebases (`$repo` / `$org/repo`). Enables the "$" trigger. */
+  codebases?: ReferenceSource
+}
+
 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.
+   * The reference chip pickers: true (default: "@" and "#" with free-form entry),
+   * false, or per-trigger sources — static lists or async `(query) => options`.
+   * "$" (codebases) is only enabled when a `codebases` source is given, so a
+   * dollar sign in ordinary prose never opens a menu.
    */
-  references?: boolean | { mentions?: string[]; tags?: string[] }
+  references?: boolean | ReferenceSources
   /**
    * Disable StarterKit's built-in undo/redo. Required when wiring Yjs
    * Collaboration, which provides its own shared history.
@@ -73,6 +84,7 @@ export function createGitbookExtensions(options: GitbookExtensionOptions = {}):
       createReferenceSuggestion({ char: "@", ...(opts.mentions ? { items: opts.mentions } : {}) }),
       createReferenceSuggestion({ char: "#", ...(opts.tags ? { items: opts.tags } : {}) })
     )
+    if (opts.codebases) list.push(createReferenceSuggestion({ char: "$", items: opts.codebases }))
   }
 
   list.push(...extensions)

package/src/editor/nodes.tsx

@@ -13,6 +13,7 @@ import {
   AtSign,
   CheckCircle2,
   ChevronDown,
+  FolderGit2,
   Hash,
   Info,
   Link2,
@@ -792,7 +793,13 @@ function ReferenceView({ node }: NodeViewProps) {
         </span>
       ) : (
         <span className={`gb-ref gb-ref-${kind}`}>
-          {kind === "mention" ? <AtSign className="gb-ref-icon" /> : <Hash className="gb-ref-icon" />}
+          {kind === "mention" ? (
+            <AtSign className="gb-ref-icon" />
+          ) : kind === "codebase" ? (
+            <FolderGit2 className="gb-ref-icon" />
+          ) : (
+            <Hash className="gb-ref-icon" />
+          )}
           {id}
         </span>
       )}
@@ -818,7 +825,14 @@ export const GbReference = Node.create({
     return [{ tag: "span[data-gb-ref]" }]
   },
   renderHTML({ HTMLAttributes, node }) {
-    const sigil = node.attrs.kind === "mention" ? "@" : node.attrs.kind === "tag" ? "#" : "^"
+    const sigil =
+      node.attrs.kind === "mention"
+        ? "@"
+        : node.attrs.kind === "tag"
+          ? "#"
+          : node.attrs.kind === "codebase"
+            ? "$"
+            : "^"
     return [
       "span",
       mergeAttributes(HTMLAttributes, { "data-gb-ref": node.attrs.kind, "data-gb-ref-id": node.attrs.id }),

package/src/editor/reference-menu.tsx

@@ -1,32 +1,88 @@
 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 { AtSign, FolderGit2, Hash, type LucideIcon } from "lucide-react"
 
 import { createSuggestionRender, type SuggestionMenuItem } from "./suggestion-menu"
 
-export type ReferenceTrigger = "@" | "#"
+export type ReferenceTrigger = "@" | "#" | "$"
 
-interface ReferenceItem extends SuggestionMenuItem {
+/** One pickable reference: the chip stores `id`; the rest only decorates the menu. */
+export interface ReferenceOption {
   id: string
+  /** Display name shown next to the id (e.g. "Luna" for `@luna`). */
+  label?: string
+  /** Secondary line (e.g. an email, "agent · claude-code", a topic). */
+  description?: string
+  /** Section header; consecutive options with the same group are listed together. */
+  group?: string
 }
 
+/**
+ * Where a trigger's options come from: a static list (filtered by the editor), or a
+ * function the host answers per query — sync or async, already filtered.
+ */
+export type ReferenceSource =
+  | readonly (string | ReferenceOption)[]
+  | ((query: string) => readonly ReferenceOption[] | Promise<readonly ReferenceOption[]>)
+
 export interface ReferenceSuggestionOptions {
   char: ReferenceTrigger
-  /** Known ids offered in the picker; free-form entry always works. */
-  items?: string[]
+  /** Options offered in the picker; free-form entry works unless disabled. */
+  items?: ReferenceSource
+  /** Offer inserting the raw query when nothing matches exactly (default true). */
+  allowFreeForm?: boolean
+}
+
+interface ReferenceItem extends SuggestionMenuItem {
+  id: string
 }
 
-const KIND: Record<ReferenceTrigger, "mention" | "tag"> = { "@": "mention", "#": "tag" }
+const KIND: Record<ReferenceTrigger, "mention" | "tag" | "codebase"> = {
+  "@": "mention",
+  "#": "tag",
+  $: "codebase",
+}
+const ICON: Record<ReferenceTrigger, LucideIcon> = { "@": AtSign, "#": Hash, $: FolderGit2 }
+const EMPTY: Record<ReferenceTrigger, string> = {
+  "@": "Type a name to mention",
+  "#": "Type a channel or tag",
+  $: "Type a codebase",
+}
+const MAX_OPTIONS = 50
+
+function normalize(option: string | ReferenceOption): ReferenceOption {
+  return typeof option === "string" ? { id: option } : option
+}
+
+function matches(option: ReferenceOption, query: string): boolean {
+  if (!query) return true
+  return [option.id, option.label ?? ""].some((value) => value.toLowerCase().includes(query))
+}
+
+/** Resolve a source for a query into options (exported for hosts' tests). */
+export async function resolveReferenceOptions(
+  source: ReferenceSource | undefined,
+  query: string,
+): Promise<ReferenceOption[]> {
+  if (source === undefined) return []
+  if (typeof source === "function") return [...(await source(query))].slice(0, MAX_OPTIONS)
+  const q = query.toLowerCase()
+  return source.map(normalize).filter((option) => matches(option, q)).slice(0, MAX_OPTIONS)
+}
 
 /**
- * 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.
+ * An `@mention` / `#tag` / `$codebase` picker built on @tiptap/suggestion. Options come
+ * from the host (static or async) and the raw query is offered as a free-form entry,
+ * so `@anything⏎` works with no source configured.
  */
-export function createReferenceSuggestion({ char, items = [] }: ReferenceSuggestionOptions) {
+export function createReferenceSuggestion({
+  char,
+  items,
+  allowFreeForm = true,
+}: ReferenceSuggestionOptions) {
   const kind = KIND[char]
-  const icon = char === "@" ? AtSign : Hash
+  const icon = ICON[char]
   return Extension.create({
     name: `${kind}Suggestion`,
     addProseMirrorPlugins() {
@@ -39,13 +95,26 @@ export function createReferenceSuggestion({ char, items = [] }: ReferenceSuggest
           // 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
+          items: async ({ query }) => {
+            let options: ReferenceOption[]
+            try {
+              options = await resolveReferenceOptions(items, query)
+            } catch {
+              options = []
+            }
+            const menu: ReferenceItem[] = options.map((option) => ({
+              id: option.id,
+              title: `${char}${option.id}`,
+              icon,
+              ...(option.label || option.description
+                ? { description: [option.label, option.description].filter(Boolean).join(" · ") }
+                : {}),
+              ...(option.group ? { group: option.group } : {}),
+            }))
+            const exact = options.some((option) => option.id.toLowerCase() === query.toLowerCase())
+            return allowFreeForm && query && !exact
+              ? [...menu, { id: query, title: `${char}${query}`, icon }]
+              : menu
           },
           command: ({ editor, range, props }) => {
             ;(editor as Editor)
@@ -58,9 +127,7 @@ export function createReferenceSuggestion({ char, items = [] }: ReferenceSuggest
               ])
               .run()
           },
-          render: createSuggestionRender<ReferenceItem>(
-            char === "@" ? "Type a name to mention" : "Type a tag"
-          ),
+          render: createSuggestionRender<ReferenceItem>(EMPTY[char]),
         }),
       ]
     },

package/src/editor/suggestion-menu.tsx

@@ -12,11 +12,15 @@ 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.
+// Shared popup used by the "/" slash menu and the "@"/"#"/"$" reference menus.
 
 export interface SuggestionMenuItem {
   title: string
   icon: LucideIcon
+  /** Secondary text shown after the title (e.g. a display name or email). */
+  description?: string
+  /** Section header; shown when it differs from the previous item's group. */
+  group?: string
 }
 
 export interface MenuProps<Item extends SuggestionMenuItem> {
@@ -97,21 +101,26 @@ export const SuggestionMenuView = forwardRef<MenuHandle, MenuProps<SuggestionMen
       >
         {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 key={`${item.group ?? ""}:${item.title}:${i}`} className="slash-row">
+            {item.group && item.group !== items[i - 1]?.group && (
+              <div className="slash-group">{item.group}</div>
+            )}
+            <button
+              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>
+              {item.description && <span className="slash-item-description">{item.description}</span>}
+            </button>
+          </div>
         ))}
       </div>
     )

package/src/index.ts

@@ -6,12 +6,17 @@ export type { PMNode } from "./editor/convert"
 // Building blocks for composing a custom editor (e.g. with Yjs collaboration
 // 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 type { GitbookExtensionOptions, ReferenceSources } from "./editor/extensions"
 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 { createReferenceSuggestion, resolveReferenceOptions } from "./editor/reference-menu"
+export type {
+  ReferenceOption,
+  ReferenceSource,
+  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"

package/src/styles.css

@@ -650,6 +650,23 @@
 .slash-item-active { background: var(--accent, #f4f4f5); }
 .slash-item svg { color: var(--muted-foreground, #6b7280); }
 .slash-empty { padding: 8px 10px; font-size: 13px; color: var(--muted-foreground, #6b7280); }
+.slash-group {
+  padding: 8px 10px 3px;
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  color: var(--muted-foreground, #6b7280);
+}
+.slash-item-description {
+  margin-left: auto;
+  padding-left: 12px;
+  overflow: hidden;
+  font-size: 12px;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  color: var(--muted-foreground, #6b7280);
+}
 
 .gb-code-live {
   display: flex;
@@ -819,6 +836,12 @@
   color: var(--gb-muted-foreground);
 }
 
+.gb-ref-codebase {
+  border: 1px solid rgba(34, 197, 94, 0.45);
+  background: rgba(34, 197, 94, 0.1);
+  color: rgb(22, 163, 74);
+}
+
 .gb-cite {
   display: inline-block;
   padding: 1px 5px;