@relevaince/mentions 0.1.0

package/README.md

@@ -0,0 +1,245 @@
+# @relevaince/mentions
+
+A structured mention engine for React. Built on Tiptap/ProseMirror internally, exposed as a single component externally.
+
+This is **not** a simple `@mention` dropdown. It is a resource-addressing language inside text — typed entity tokens that look like text but carry structured data. Think Slack, Notion, or Linear mentions.
+
+## Features
+
+- **Multiple trigger characters** — `@`, `#`, `:`, or any custom trigger
+- **Nested suggestions** — drill into workspaces, then pick a file inside
+- **Async providers** — fetch suggestions from any API
+- **Structured output** — returns `{ markdown, tokens, plainText }` on every change
+- **Markdown serialization** — `@[label](id)` token syntax for storage and LLM context
+- **Headless styling** — zero bundled CSS, style via `data-*` attributes with Tailwind or plain CSS
+- **Accessible** — full ARIA combobox pattern with keyboard navigation
+- **SSR compatible** — safe for Next.js with `"use client"` directive
+
+## Install
+
+```bash
+npm install @relevaince/mentions
+```
+
+Peer dependencies:
+
+```bash
+npm install react react-dom
+```
+
+## Quick start
+
+```tsx
+import { MentionsInput, type MentionProvider } from "@relevaince/mentions";
+
+const workspaceProvider: MentionProvider = {
+  trigger: "@",
+  name: "Workspaces",
+  async getRootItems(query) {
+    const res = await fetch(`/api/workspaces?q=${query}`);
+    return res.json();
+  },
+  async getChildren(parent, query) {
+    const res = await fetch(`/api/workspaces/${parent.id}/files?q=${query}`);
+    return res.json();
+  },
+};
+
+function Chat() {
+  return (
+    <MentionsInput
+      providers={[workspaceProvider]}
+      onChange={(output) => {
+        console.log(output.markdown);  // "Summarize @[Marketing](ws_123)"
+        console.log(output.tokens);    // [{ id: "ws_123", type: "workspace", label: "Marketing" }]
+        console.log(output.plainText); // "Summarize Marketing"
+      }}
+      onSubmit={(output) => sendMessage(output)}
+      placeholder="Ask anything..."
+    />
+  );
+}
+```
+
+## Core concepts
+
+### MentionToken
+
+The fundamental data model. Every mention in the editor is a typed token:
+
+```ts
+type MentionToken = {
+  id: string;       // unique entity identifier
+  type: string;     // "workspace" | "contract" | "file" | "web" | custom
+  label: string;    // display text
+  data?: unknown;   // optional payload, passed through untouched
+};
+```
+
+### MentionProvider
+
+Register one provider per trigger character. Each provider fetches suggestions and optionally supports nested drill-down:
+
+```ts
+type MentionProvider = {
+  trigger: string;                                            // "@", "#", ":"
+  name: string;                                               // human label
+  getRootItems: (query: string) => Promise<MentionItem[]>;
+  getChildren?: (parent: MentionItem, query: string) => Promise<MentionItem[]>;
+};
+```
+
+### MentionItem
+
+Items returned by providers:
+
+```ts
+type MentionItem = {
+  id: string;
+  type: string;
+  label: string;
+  icon?: ReactNode;        // rendered before the label
+  description?: string;    // secondary text
+  hasChildren?: boolean;   // when true, selecting drills into a child level
+  data?: unknown;
+};
+```
+
+### MentionsOutput
+
+Structured output returned on every change and submit:
+
+```ts
+type MentionsOutput = {
+  markdown: string;        // "@[Marketing](ws_123) summarize files"
+  tokens: MentionToken[];  // [{ id: "ws_123", type: "workspace", label: "Marketing" }]
+  plainText: string;       // "Marketing summarize files"
+};
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | — | Initial markdown content with `@[label](id)` tokens |
+| `providers` | `MentionProvider[]` | **required** | Suggestion providers, one per trigger |
+| `onChange` | `(output: MentionsOutput) => void` | — | Called on every content change |
+| `onSubmit` | `(output: MentionsOutput) => void` | — | Called on Enter / Cmd+Enter |
+| `placeholder` | `string` | `"Type a message..."` | Placeholder text |
+| `autoFocus` | `boolean` | `false` | Focus editor on mount |
+| `disabled` | `boolean` | `false` | Disable editing |
+| `className` | `string` | — | CSS class on the wrapper |
+| `maxLength` | `number` | — | Max plain text character count |
+| `renderItem` | `(item, depth) => ReactNode` | — | Custom suggestion item renderer |
+| `renderChip` | `(token) => ReactNode` | — | Custom inline mention chip renderer |
+
+## Nested mentions
+
+The killer feature. When a `MentionItem` has `hasChildren: true`, selecting it drills into the next level using `provider.getChildren()`:
+
+```
+@workspace → choose workspace → choose file inside workspace
+@contract  → choose contract  → choose clause
+:web       → choose provider  → type query
+```
+
+Keyboard navigation:
+
+| Key | Action |
+|-----|--------|
+| `↑` `↓` | Navigate suggestions |
+| `Enter` `→` | Select / drill into children |
+| `←` `Backspace` | Go back one level |
+| `Escape` | Close suggestions |
+
+## Markdown format
+
+Mentions serialize to a compact token syntax:
+
+```
+@[Marketing Workspace](ws_123) summarize the latest files
+```
+
+Use the standalone helpers for server-side processing:
+
+```ts
+import { serializeToMarkdown, parseFromMarkdown } from "@relevaince/mentions";
+
+// Parse markdown into a Tiptap-compatible JSON document
+const doc = parseFromMarkdown("Check @[NDA](contract:c_44) for risks");
+
+// Serialize a Tiptap JSON document back to markdown
+const md = serializeToMarkdown(doc);
+```
+
+## Styling
+
+Zero bundled CSS. Every element exposes `data-*` attributes for styling:
+
+```css
+/* Mention chips inside the editor */
+[data-mention]                      { /* base chip */ }
+[data-mention][data-type="workspace"] { /* workspace chip */ }
+[data-mention][data-type="contract"]  { /* contract chip */ }
+
+/* Suggestion popover */
+[data-suggestions]                  { /* popover wrapper */ }
+[data-suggestion-item]              { /* each item */ }
+[data-suggestion-item-active]       { /* highlighted item */ }
+[data-suggestion-breadcrumb]        { /* breadcrumb bar (nested) */ }
+[data-suggestion-loading]           { /* loading indicator */ }
+```
+
+Example with Tailwind:
+
+```css
+[data-mention] {
+  @apply bg-blue-500/10 text-blue-600 rounded px-1 py-0.5 font-medium text-sm;
+}
+
+[data-suggestions] {
+  @apply bg-white border border-neutral-200 rounded-lg shadow-lg
+         min-w-[240px] max-h-[280px] overflow-y-auto py-1;
+}
+
+[data-suggestion-item] {
+  @apply flex items-center gap-2 px-3 py-1.5 cursor-pointer text-sm;
+}
+
+[data-suggestion-item-active] {
+  @apply bg-neutral-100;
+}
+```
+
+## Architecture
+
+```
+<MentionsInput>
+  ├── Tiptap Editor (ProseMirror)
+  │     ├── MentionNode Extension    — inline atom nodes with id/label/type
+  │     ├── Suggestion Plugin        — multi-trigger detection + popover callbacks
+  │     ├── Submit Extension         — Enter / Cmd+Enter handling
+  │     └── Markdown Serializer      — doc ↔ @[label](id) format
+  └── SuggestionList (React)         — headless popover with ARIA
+```
+
+Consumers interact with a single React component. Tiptap and ProseMirror are internal implementation details.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the library
+npm run build
+
+# Run the demo app
+cd demo && npm install && npx vite
+```
+
+The demo app registers mock providers for workspaces, contracts, and web search. It displays live structured output below the editor.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,127 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { JSONContent } from '@tiptap/core';
+
+/**
+ * A single suggestion item returned by a provider.
+ */
+type MentionItem = {
+    /** Unique identifier for this item. */
+    id: string;
+    /** Entity kind — maps to `MentionToken.type` on insertion. */
+    type: string;
+    /** Display label shown in the suggestion list. */
+    label: string;
+    /** Optional icon rendered before the label. */
+    icon?: ReactNode;
+    /** Optional secondary text. */
+    description?: string;
+    /** When `true`, selecting this item drills into a child level instead of inserting. */
+    hasChildren?: boolean;
+    /** Optional payload carried through to `MentionToken.data`. */
+    data?: unknown;
+};
+/**
+ * Hierarchical suggestion source registered per trigger character.
+ *
+ * Consumers provide one provider per trigger (e.g. "@", "#", ":").
+ * The engine calls `getRootItems` first, then `getChildren` when
+ * the user drills into a nested level.
+ */
+type MentionProvider = {
+    /** The character(s) that activate this provider — e.g. "@", "#", ":". */
+    trigger: string;
+    /** Human-readable name for this provider (used in ARIA labels). */
+    name: string;
+    /** Fetch top-level suggestions for the current query. */
+    getRootItems: (query: string) => Promise<MentionItem[]>;
+    /** Fetch child suggestions when the user drills into `parent`. */
+    getChildren?: (parent: MentionItem, query: string) => Promise<MentionItem[]>;
+};
+
+/**
+ * Core data model for a mention entity embedded in text.
+ *
+ * Stored as an inline ProseMirror node — the rendered text
+ * is derived from `label`, but the underlying identity is `id` + `type`.
+ */
+type MentionToken = {
+    /** Unique identifier for the referenced entity. */
+    id: string;
+    /** Entity kind — e.g. "workspace", "contract", "file", "web", or any custom string. */
+    type: string;
+    /** Human-readable display label. */
+    label: string;
+    /** Optional full entity payload — opaque to the library, passed through untouched. */
+    data?: unknown;
+};
+
+/**
+ * Structured output returned on every editor change.
+ *
+ * Gives consumers three representations of the same content:
+ * - `markdown`  — serialised with `@[label](id)` tokens, for storage / LLM context.
+ * - `tokens`    — flat array of every mention in document order.
+ * - `plainText` — labels inlined, for display / search indexing.
+ */
+type MentionsOutput = {
+    /** Markdown string with mention tokens encoded as `@[label](id)`. */
+    markdown: string;
+    /** Ordered array of all mention tokens in the document. */
+    tokens: MentionToken[];
+    /** Plain text with mention labels substituted inline. */
+    plainText: string;
+};
+
+/**
+ * Props for the public `<MentionsInput>` component.
+ */
+type MentionsInputProps = {
+    /** Initial content as a markdown string (with `@[label](id)` tokens). */
+    value?: string;
+    /** Suggestion providers — one per trigger character. */
+    providers: MentionProvider[];
+    /** Called on every content change with the structured output. */
+    onChange?: (output: MentionsOutput) => void;
+    /** Placeholder text shown when the editor is empty. */
+    placeholder?: string;
+    /** Focus the editor on mount. */
+    autoFocus?: boolean;
+    /** Disable editing. */
+    disabled?: boolean;
+    /** CSS class applied to the outermost wrapper. */
+    className?: string;
+    /** Called when the user presses Enter (or Cmd+Enter). */
+    onSubmit?: (output: MentionsOutput) => void;
+    /** Maximum character count (plain text length). */
+    maxLength?: number;
+    /** Custom renderer for suggestion list items. */
+    renderItem?: (item: MentionItem, depth: number) => ReactNode;
+    /** Custom renderer for inline mention chips. */
+    renderChip?: (token: MentionToken) => ReactNode;
+};
+
+/**
+ * `<MentionsInput>` — the single public component.
+ *
+ * A structured text editor with typed entity tokens.
+ * Consumers register `providers` for each trigger character,
+ * and receive structured output via `onChange` and `onSubmit`.
+ */
+declare function MentionsInput({ value, providers, onChange, placeholder, autoFocus, disabled, className, onSubmit, maxLength, renderItem, renderChip, }: MentionsInputProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Serialize a Tiptap JSON document to a markdown string.
+ *
+ * Mention nodes are encoded as `@[label](id)` tokens.
+ * All other text passes through verbatim.
+ */
+declare function serializeToMarkdown(doc: JSONContent): string;
+
+/**
+ * Parse a markdown string (with `@[label](id)` or `@[label](type:id)` tokens)
+ * into a Tiptap-compatible JSON document.
+ */
+declare function parseFromMarkdown(markdown: string): JSONContent;
+
+export { type MentionItem, type MentionProvider, type MentionToken, MentionsInput, type MentionsInputProps, type MentionsOutput, parseFromMarkdown, serializeToMarkdown };

package/dist/index.d.ts

@@ -0,0 +1,127 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { JSONContent } from '@tiptap/core';
+
+/**
+ * A single suggestion item returned by a provider.
+ */
+type MentionItem = {
+    /** Unique identifier for this item. */
+    id: string;
+    /** Entity kind — maps to `MentionToken.type` on insertion. */
+    type: string;
+    /** Display label shown in the suggestion list. */
+    label: string;
+    /** Optional icon rendered before the label. */
+    icon?: ReactNode;
+    /** Optional secondary text. */
+    description?: string;
+    /** When `true`, selecting this item drills into a child level instead of inserting. */
+    hasChildren?: boolean;
+    /** Optional payload carried through to `MentionToken.data`. */
+    data?: unknown;
+};
+/**
+ * Hierarchical suggestion source registered per trigger character.
+ *
+ * Consumers provide one provider per trigger (e.g. "@", "#", ":").
+ * The engine calls `getRootItems` first, then `getChildren` when
+ * the user drills into a nested level.
+ */
+type MentionProvider = {
+    /** The character(s) that activate this provider — e.g. "@", "#", ":". */
+    trigger: string;
+    /** Human-readable name for this provider (used in ARIA labels). */
+    name: string;
+    /** Fetch top-level suggestions for the current query. */
+    getRootItems: (query: string) => Promise<MentionItem[]>;
+    /** Fetch child suggestions when the user drills into `parent`. */
+    getChildren?: (parent: MentionItem, query: string) => Promise<MentionItem[]>;
+};
+
+/**
+ * Core data model for a mention entity embedded in text.
+ *
+ * Stored as an inline ProseMirror node — the rendered text
+ * is derived from `label`, but the underlying identity is `id` + `type`.
+ */
+type MentionToken = {
+    /** Unique identifier for the referenced entity. */
+    id: string;
+    /** Entity kind — e.g. "workspace", "contract", "file", "web", or any custom string. */
+    type: string;
+    /** Human-readable display label. */
+    label: string;
+    /** Optional full entity payload — opaque to the library, passed through untouched. */
+    data?: unknown;
+};
+
+/**
+ * Structured output returned on every editor change.
+ *
+ * Gives consumers three representations of the same content:
+ * - `markdown`  — serialised with `@[label](id)` tokens, for storage / LLM context.
+ * - `tokens`    — flat array of every mention in document order.
+ * - `plainText` — labels inlined, for display / search indexing.
+ */
+type MentionsOutput = {
+    /** Markdown string with mention tokens encoded as `@[label](id)`. */
+    markdown: string;
+    /** Ordered array of all mention tokens in the document. */
+    tokens: MentionToken[];
+    /** Plain text with mention labels substituted inline. */
+    plainText: string;
+};
+
+/**
+ * Props for the public `<MentionsInput>` component.
+ */
+type MentionsInputProps = {
+    /** Initial content as a markdown string (with `@[label](id)` tokens). */
+    value?: string;
+    /** Suggestion providers — one per trigger character. */
+    providers: MentionProvider[];
+    /** Called on every content change with the structured output. */
+    onChange?: (output: MentionsOutput) => void;
+    /** Placeholder text shown when the editor is empty. */
+    placeholder?: string;
+    /** Focus the editor on mount. */
+    autoFocus?: boolean;
+    /** Disable editing. */
+    disabled?: boolean;
+    /** CSS class applied to the outermost wrapper. */
+    className?: string;
+    /** Called when the user presses Enter (or Cmd+Enter). */
+    onSubmit?: (output: MentionsOutput) => void;
+    /** Maximum character count (plain text length). */
+    maxLength?: number;
+    /** Custom renderer for suggestion list items. */
+    renderItem?: (item: MentionItem, depth: number) => ReactNode;
+    /** Custom renderer for inline mention chips. */
+    renderChip?: (token: MentionToken) => ReactNode;
+};
+
+/**
+ * `<MentionsInput>` — the single public component.
+ *
+ * A structured text editor with typed entity tokens.
+ * Consumers register `providers` for each trigger character,
+ * and receive structured output via `onChange` and `onSubmit`.
+ */
+declare function MentionsInput({ value, providers, onChange, placeholder, autoFocus, disabled, className, onSubmit, maxLength, renderItem, renderChip, }: MentionsInputProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Serialize a Tiptap JSON document to a markdown string.
+ *
+ * Mention nodes are encoded as `@[label](id)` tokens.
+ * All other text passes through verbatim.
+ */
+declare function serializeToMarkdown(doc: JSONContent): string;
+
+/**
+ * Parse a markdown string (with `@[label](id)` or `@[label](type:id)` tokens)
+ * into a Tiptap-compatible JSON document.
+ */
+declare function parseFromMarkdown(markdown: string): JSONContent;
+
+export { type MentionItem, type MentionProvider, type MentionToken, MentionsInput, type MentionsInputProps, type MentionsOutput, parseFromMarkdown, serializeToMarkdown };