@djangocfg/ui-tools 2.1.291 → 2.1.292

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.291",
+  "version": "2.1.292",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -91,8 +91,8 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.291",
-    "@djangocfg/ui-core": "^2.1.291",
+    "@djangocfg/i18n": "^2.1.292",
+    "@djangocfg/ui-core": "^2.1.292",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -102,6 +102,7 @@
     "zustand": "^5.0.0"
   },
   "dependencies": {
+    "@floating-ui/dom": "^1.7.4",
     "@rjsf/core": "^6.1.2",
     "@rjsf/utils": "^6.1.2",
     "@rjsf/validator-ajv8": "^6.1.2",
@@ -139,10 +140,10 @@
     "@maplibre/maplibre-gl-geocoder": "^1.7.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.291",
+    "@djangocfg/i18n": "^2.1.292",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.291",
-    "@djangocfg/ui-core": "^2.1.291",
+    "@djangocfg/typescript-config": "^2.1.292",
+    "@djangocfg/ui-core": "^2.1.292",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^24.7.2",

package/src/tools/MarkdownEditor/MarkdownEditor.story.tsx

@@ -1,7 +1,8 @@
 import { defineStory } from '@djangocfg/playground';
 import { MarkdownEditor } from './MarkdownEditor';
-import { useState } from 'react';
-import type { MentionConfig } from './types';
+import { mentionPresets } from './mentionPresets';
+import { useState, type ReactNode } from 'react';
+import type { MentionConfig, MentionMarkdownRenderer } from './types';
 
 export default defineStory({
   title: 'Tools/Markdown Editor',
@@ -109,6 +110,111 @@ export function Compact() {
   );
 }
 
+export function WithCustomUriPreset() {
+  const [value, setValue] = useState(
+    'Reference @Alice and @Bob — markdown will carry machine-readable URIs.\n\nType @ to add more.',
+  );
+
+  return (
+    <SerializationDemo
+      description={
+        <>
+          <code>mentionPresets.customUri('myapp', 'user')</code> — emits
+          <code>{' @[Label](myapp://user/id)'}</code>. Useful when downstream
+          parses the markdown back into deep-links while keeping the visible
+          <code>@</code> handle.
+        </>
+      }
+      value={value}
+      onChange={setValue}
+      renderMarkdown={mentionPresets.customUri('myapp', 'user')}
+    />
+  );
+}
+
+export function WithMarkdownLinkPreset() {
+  const [value, setValue] = useState('Ping @Alice when ready, cc @Charlie.');
+
+  return (
+    <SerializationDemo
+      description={
+        <>
+          <code>mentionPresets.markdownLink('https://example.com/u/')</code> —
+          serializes mentions as ordinary clickable links: <code>[@Label](https://example.com/u/id)</code>.
+        </>
+      }
+      value={value}
+      onChange={setValue}
+      renderMarkdown={mentionPresets.markdownLink('https://example.com/u/')}
+    />
+  );
+}
+
+export function WithCustomRenderer() {
+  const [value, setValue] = useState('Tag @Alice and @Bob to assign the task.');
+
+  // Hand-rolled serializer — any (attrs) => string works.
+  const renderMarkdown: MentionMarkdownRenderer = ({ id, label }) =>
+    `{{user:${id}|${label || 'unknown'}}}`;
+
+  return (
+    <SerializationDemo
+      description={
+        <>
+          Inline custom renderer: <code>{`({ id, label }) => \`{{user:\${id}|\${label}}}\``}</code>.
+          Shows that the serializer is just a function — you control the wire format.
+        </>
+      }
+      value={value}
+      onChange={setValue}
+      renderMarkdown={renderMarkdown}
+    />
+  );
+}
+
+interface SerializationDemoProps {
+  description: ReactNode;
+  value: string;
+  onChange: (v: string) => void;
+  renderMarkdown: MentionMarkdownRenderer;
+}
+
+function SerializationDemo({ description, value, onChange, renderMarkdown }: SerializationDemoProps) {
+  const mentions: MentionConfig = { ...MENTION_ITEMS, renderMarkdown };
+
+  return (
+    <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 16, maxWidth: 900 }}>
+      <div>
+        <p style={{ fontSize: 12, opacity: 0.7, marginBottom: 8 }}>{description}</p>
+        <MarkdownEditor
+          value={value}
+          onChange={onChange}
+          mentions={mentions}
+          placeholder="Type @ to insert a mention..."
+        />
+      </div>
+      <div>
+        <div style={{ fontSize: 11, opacity: 0.5, marginBottom: 4, textTransform: 'uppercase', letterSpacing: 0.5 }}>
+          Serialized markdown
+        </div>
+        <pre
+          style={{
+            fontSize: 12,
+            padding: 12,
+            background: 'rgba(127,127,127,0.08)',
+            borderRadius: 6,
+            whiteSpace: 'pre-wrap',
+            wordBreak: 'break-word',
+            margin: 0,
+          }}
+        >
+          {value || '(empty)'}
+        </pre>
+      </div>
+    </div>
+  );
+}
+
 function RawPreview({ value }: { value: string }) {
   return (
     <details style={{ marginTop: 16 }}>

package/src/tools/MarkdownEditor/MarkdownEditor.tsx

@@ -12,7 +12,8 @@ import {
   List, ListOrdered, Quote, Minus, Code, type LucideIcon,
 } from 'lucide-react';
 import { createMentionSuggestion } from './createMentionSuggestion';
-import type { MentionConfig } from './types';
+import { mentionPresets } from './mentionPresets';
+import type { MentionAttrs, MentionConfig } from './types';
 import './styles.css';
 
 // ── Helpers ──
@@ -117,8 +118,51 @@ export function MarkdownEditor({
     ];
 
     if (mentions) {
+      // ── Why .extend() with renderMarkdown ──
+      //
+      // Tiptap's `Mention` extension ships a default markdown serializer
+      // (via `createInlineMarkdownSpec`, see @tiptap/extension-mention)
+      // that emits a shortcode like `[@ id="..." label="..."]`. That's
+      // round-trippable but useless for most consumers: a chat composer
+      // feeding an LLM wants `@<label>`, a deep-linking app wants a
+      // markdown link, etc.
+      //
+      // `renderText` only affects `editor.getText()` and the rendered
+      // node — it does NOT influence `@tiptap/markdown`'s serializer.
+      // The serializer reads `renderMarkdown` off the extension config
+      // (see MarkdownManager.registerExtension → getExtensionField).
+      // Overriding it via `.extend({ renderMarkdown })` replaces the
+      // shortcode output with whatever the consumer supplied (or the
+      // `plainAt` default — see ./mentionPresets.ts).
+      //
+      // Renderer-choice capture: useEditor only initialises once, so the
+      // chosen renderer is captured by closure on first render. This is
+      // intentional — swapping renderers per render would mean tearing
+      // the editor down anyway, which we don't do for any other prop.
+      //
+      // Round-trip note: we intentionally do NOT also override
+      // `parseMarkdown` / `markdownTokenizer`. Once a mention is
+      // serialized, parsing it back would need the original mention
+      // items list to look up the id, which we don't have at parse time.
+      // Mentions are write-only by design here — `setContent(value)`
+      // after submit gets back a plain string, which is fine for the
+      // chat use case.
+      const renderMarkdown = mentions.renderMarkdown ?? mentionPresets.plainAt;
       exts.push(
-        Mention.configure({
+        Mention.extend({
+          renderMarkdown(node) {
+            const raw = node.attrs as { label?: string | null; id?: string | null };
+            const attrs: MentionAttrs = {
+              id: raw?.id ?? '',
+              label: raw?.label ?? '',
+            };
+            // Defensive: if both are empty (shouldn't happen for a real
+            // mention node, but `setContent` of malformed data could),
+            // emit nothing rather than a stray "@" or invalid link.
+            if (!attrs.id && !attrs.label) return '';
+            return renderMarkdown(attrs);
+          },
+        }).configure({
           HTMLAttributes: { class: 'markdown-mention' },
           suggestion: createMentionSuggestion(mentions),
           renderText: ({ node }) => `@${node.attrs.label}`,

package/src/tools/MarkdownEditor/README.md

@@ -10,6 +10,8 @@ WYSIWYG markdown editor based on Tiptap. Renders markdown visually (headings, li
 - Blockquotes with left border
 - Horizontal rules
 - Toolbar with icon buttons
+- `@`-mentions with auto-flipping popup (`@floating-ui/dom`)
+- Customizable markdown serialization for mentions (six built-in presets)
 - Markdown input/output (stored as plain markdown string)
 - SSR-safe (`immediatelyRender: false`)
 
@@ -31,6 +33,18 @@ function MyComponent() {
 }
 ```
 
+## CSS
+
+Two ways to load styles, depending on your build:
+
+```ts
+// Tailwind-based apps — pulls in source utilities so Tailwind's JIT picks them up.
+import '@djangocfg/ui-tools/styles';
+
+// Plain Vite / webpack / CRA — pre-compiled CSS, no Tailwind required.
+import '@djangocfg/ui-tools/dist.css';
+```
+
 ## Props
 
 | Prop | Type | Default | Description |
@@ -42,9 +56,18 @@ function MyComponent() {
 | `className` | `string` | — | Additional CSS class |
 | `disabled` | `boolean` | `false` | Read-only mode |
 | `showToolbar` | `boolean` | `true` | Show formatting toolbar |
-| `mentions` | `MentionConfig` | — | @mention autocomplete config |
+| `mentions` | `MentionConfig` | — | `@`-mention autocomplete config |
 | `onMentionIdsChange` | `(ids: string[]) => void` | — | Called when mentioned IDs change |
 
+### `MentionConfig` fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `items` | `MentionItem[]` | required | Available mention items (`id`, `label`, optional `description`, `thumbnail`) |
+| `trigger` | `string` | `'@'` | Trigger character |
+| `maxItems` | `number` | `5` | Max items shown in dropdown |
+| `renderMarkdown` | `MentionMarkdownRenderer` | `mentionPresets.plainAt` | Serializes a mention to markdown — see below |
+
 ## Mentions
 
 ```tsx
@@ -61,8 +84,64 @@ function MyComponent() {
 />
 ```
 
-Type `@` to trigger autocomplete. Mentions render as inline chips.
+Type `@` to trigger autocomplete. Mentions render as inline chips. The popup auto-flips above the trigger when there isn't enough room below, and tracks scroll/resize via `autoUpdate` — viewport-aware out of the box.
+
+> Heads-up: Tiptap initialises the editor exactly once. If `mentions` is `undefined` on first render and becomes truthy later, the extension is never installed. Pass `{ items: [] }` from the start and mutate `.items` in place if items load async.
+
+## Mention serialization
+
+By default Tiptap's `Mention` extension emits a useless shortcode like `[@ id="..." label="..."]` into markdown. `MarkdownEditor` overrides that with the renderer from `MentionConfig.renderMarkdown` (defaults to `mentionPresets.plainAt`, which yields `@<label>`).
+
+Six presets are exported from `@djangocfg/ui-tools`:
+
+```tsx
+import { MarkdownEditor, mentionPresets } from '@djangocfg/ui-tools';
+
+<MarkdownEditor
+  value={text}
+  onChange={setText}
+  mentions={{
+    items,
+    renderMarkdown: mentionPresets.customUri('cmdop', 'machine'),
+  }}
+/>
+```
+
+| Preset | Output for `{ label: 'Vps-audi', id: 'uuid' }` |
+|--------|-------------------------------------------------|
+| `plainAt` *(default)* | `@Vps-audi` |
+| `plainLabel` | `Vps-audi` |
+| `markdownLink(baseUrl)` | `[@Vps-audi](baseUrl/uuid)` |
+| `customUri(scheme, kind)` | `@[Vps-audi](scheme://kind/uuid)` |
+| `slackStyle` | `<@uuid>` |
+| `htmlSpan(className?)` | `<span class="mention" data-mention-id="uuid">@Vps-audi</span>` |
+
+Pick by use case:
+
+- **`plainAt`** — chat composers feeding an LLM that reads `@<label>` natively.
+- **`customUri`** — chat that also wants machine-readable IDs in `href` for downstream parsing (e.g. `@[Vps-audi](cmdop://machine/uuid)`).
+- **`markdownLink`** — clickable mentions linking to a profile / detail page.
+- **`slackStyle`** — interop with Slack-like backends that resolve `<@id>` server-side.
+- **`htmlSpan`** — markdown consumers that allow inline HTML and want chip styling baked in.
+- **`plainLabel`** — bare display string (no `@`), e.g. for `/`-commands or non-mention triggers.
+
+### Custom renderer
+
+The signature is just `(attrs: MentionAttrs) => string`:
+
+```tsx
+import type { MentionMarkdownRenderer } from '@djangocfg/ui-tools';
+
+const renderMention: MentionMarkdownRenderer = ({ id, label }) =>
+  `{{user:${id}|${label}}}`;
+
+<MarkdownEditor mentions={{ items, renderMarkdown: renderMention }} ... />
+```
+
+Either `id` or `label` may be empty strings if upstream config didn't populate them — fall back accordingly. Returning `''` drops the mention from the output.
+
+> Mentions are write-only: the markdown isn't parsed back into mention nodes on `setContent`. After submit/reset, the editor receives a plain string — fine for chat composers.
 
 ## Dependencies
 
-All Tiptap packages are included as direct dependencies — no extra installs needed.
+All Tiptap packages and `@floating-ui/dom` are direct dependencies — no extra installs needed.

package/src/tools/MarkdownEditor/createMentionSuggestion.ts

@@ -1,5 +1,6 @@
 import { ReactRenderer } from '@tiptap/react';
 import type { SuggestionOptions } from '@tiptap/suggestion';
+import { autoUpdate, computePosition, flip, offset, shift } from '@floating-ui/dom';
 import { MentionList, type MentionListRef } from './MentionList';
 import type { MentionItem, MentionConfig } from './types';
 
@@ -21,6 +22,47 @@ export function createMentionSuggestion(
     render: () => {
       let component: ReactRenderer<MentionListRef> | null = null;
       let popup: HTMLDivElement | null = null;
+      let cleanupAutoUpdate: (() => void) | null = null;
+      let getReferenceRect: (() => DOMRect | null) | null = null;
+
+      // Floating-UI virtual element backed by Tiptap's clientRect.
+      // We re-read it on every reposition so caret movement is tracked.
+      const buildVirtualElement = () => ({
+        getBoundingClientRect: () => {
+          const rect = getReferenceRect?.();
+          // Fallback to a zero-sized rect at origin if the editor is detached
+          // (e.g. mid-teardown). Floating-UI tolerates this.
+          return rect ?? new DOMRect(0, 0, 0, 0);
+        },
+      });
+
+      const updatePosition = () => {
+        if (!popup) return;
+        const virtualEl = buildVirtualElement();
+        void computePosition(virtualEl, popup, {
+          placement: 'bottom-start',
+          middleware: [
+            offset(4),
+            flip({ fallbackPlacements: ['top-start'] }),
+            shift({ padding: 8 }),
+          ],
+        }).then(({ x, y }) => {
+          if (!popup) return;
+          // transform is more performant than top/left and avoids
+          // sub-pixel layout thrash during scroll/resize.
+          popup.style.transform = `translate3d(${Math.round(x)}px, ${Math.round(y)}px, 0)`;
+        });
+      };
+
+      const teardown = () => {
+        cleanupAutoUpdate?.();
+        cleanupAutoUpdate = null;
+        popup?.remove();
+        popup = null;
+        component?.destroy();
+        component = null;
+        getReferenceRect = null;
+      };
 
       return {
         onStart: (props) => {
@@ -35,16 +77,17 @@ export function createMentionSuggestion(
           });
 
           popup = document.createElement('div');
-          popup.style.cssText = 'position: absolute; z-index: 99999;';
+          // top/left at 0; actual position is applied via transform by computePosition.
+          popup.style.cssText = 'position: absolute; top: 0; left: 0; z-index: 99999;';
           popup.appendChild(component.element);
+          document.body.appendChild(popup);
 
-          const rect = props.clientRect?.();
-          if (rect) {
-            popup.style.top = `${rect.bottom + window.scrollY + 4}px`;
-            popup.style.left = `${rect.left + window.scrollX}px`;
-          }
+          getReferenceRect = () => props.clientRect?.() ?? null;
 
-          document.body.appendChild(popup);
+          // autoUpdate handles scroll, resize, ancestor scroll/resize, layout shifts.
+          // It calls updatePosition synchronously on registration too — no manual first call needed.
+          const virtualEl = buildVirtualElement();
+          cleanupAutoUpdate = autoUpdate(virtualEl, popup, updatePosition);
         },
 
         onUpdate: (props) => {
@@ -55,25 +98,21 @@ export function createMentionSuggestion(
             },
           });
 
-          const rect = props.clientRect?.();
-          if (rect && popup) {
-            popup.style.top = `${rect.bottom + window.scrollY + 4}px`;
-            popup.style.left = `${rect.left + window.scrollX}px`;
-          }
+          // Refresh reference accessor so autoUpdate sees the new caret rect.
+          getReferenceRect = () => props.clientRect?.() ?? null;
+          updatePosition();
         },
 
         onKeyDown: (props) => {
           if (props.event.key === 'Escape') {
-            popup?.remove();
-            component?.destroy();
+            teardown();
             return true;
           }
           return component?.ref?.onKeyDown(props.event as unknown as React.KeyboardEvent) ?? false;
         },
 
         onExit: () => {
-          popup?.remove();
-          component?.destroy();
+          teardown();
         },
       };
     },

package/src/tools/MarkdownEditor/index.ts

@@ -1,3 +1,9 @@
 export { MarkdownEditor } from './MarkdownEditor';
 export type { MarkdownEditorProps } from './MarkdownEditor';
-export type { MentionItem, MentionConfig } from './types';
+export type {
+  MentionItem,
+  MentionConfig,
+  MentionAttrs,
+  MentionMarkdownRenderer,
+} from './types';
+export { mentionPresets } from './mentionPresets';

package/src/tools/MarkdownEditor/mentionPresets.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Inline-assertion smoke test for mentionPresets.
+ *
+ * The `@djangocfg/ui-tools` package has no test runner configured
+ * (`package.json` only has build / clean / dev / playground / check).
+ * Rather than introduce vitest just for this, we keep the assertions
+ * inline and runnable as a one-shot Node script.
+ *
+ * Run:
+ *   cd packages/ui-tools
+ *   npx tsx src/tools/MarkdownEditor/mentionPresets.test.ts
+ *
+ * Or just trust `npm run check` (tsc --noEmit) to catch type drift —
+ * the file is excluded from tsup's `entry`, so it never ships in `dist`.
+ */
+import { mentionPresets } from './mentionPresets';
+
+let failures = 0;
+const eq = (label: string, got: string, want: string) => {
+  const ok = got === want;
+  if (!ok) failures += 1;
+  // eslint-disable-next-line no-console
+  console.log(`${ok ? 'PASS' : 'FAIL'}  ${label}`);
+  if (!ok) {
+    // eslint-disable-next-line no-console
+    console.log(`        got:  ${JSON.stringify(got)}`);
+    // eslint-disable-next-line no-console
+    console.log(`        want: ${JSON.stringify(want)}`);
+  }
+};
+const includes = (label: string, got: string, needle: string) => {
+  const ok = got.includes(needle);
+  if (!ok) failures += 1;
+  // eslint-disable-next-line no-console
+  console.log(`${ok ? 'PASS' : 'FAIL'}  ${label}`);
+  if (!ok) {
+    // eslint-disable-next-line no-console
+    console.log(`        got:    ${JSON.stringify(got)}`);
+    // eslint-disable-next-line no-console
+    console.log(`        needle: ${JSON.stringify(needle)}`);
+  }
+};
+
+// ── plainAt ──
+eq(
+  'plainAt label present',
+  mentionPresets.plainAt({ label: 'Vps-audi', id: 'uuid' }),
+  '@Vps-audi',
+);
+eq(
+  'plainAt empty label falls back to id',
+  mentionPresets.plainAt({ label: '', id: 'uuid' }),
+  '@uuid',
+);
+
+// ── plainLabel ──
+eq(
+  'plainLabel returns label as-is',
+  mentionPresets.plainLabel({ label: 'X', id: '1' }),
+  'X',
+);
+
+// ── markdownLink ──
+{
+  const link = mentionPresets.markdownLink('https://x.com/u/');
+  const out = link({ label: 'X Y', id: '1' });
+  includes('markdownLink contains label text', out, 'X Y');
+  includes('markdownLink contains encoded id', out, 'https://x.com/u/1');
+  includes('markdownLink wraps with [@...](', out, '[@X Y](https://x.com/u/1)');
+
+  const escaped = link({ label: 'A_B*C[D]', id: 'id 2' });
+  includes('markdownLink escapes label specials', escaped, '\\_');
+  includes('markdownLink escapes brackets', escaped, '\\[');
+  includes('markdownLink escapes asterisk', escaped, '\\*');
+  includes('markdownLink encodes id space', escaped, 'id%202');
+}
+
+// ── customUri ──
+eq(
+  'customUri Notion-style',
+  mentionPresets.customUri('cmdop', 'machine')({ label: 'My Box', id: 'uuid' }),
+  '@[My Box](cmdop://machine/uuid)',
+);
+
+// ── slackStyle ──
+eq(
+  'slackStyle drops label, emits <@id>',
+  mentionPresets.slackStyle({ label: 'X', id: 'U123' }),
+  '<@U123>',
+);
+
+// ── htmlSpan ──
+{
+  const out = mentionPresets.htmlSpan('m')({ label: 'X', id: '1' });
+  includes('htmlSpan uses class', out, 'class="m"');
+  includes('htmlSpan exposes data-mention-id', out, 'data-mention-id="1"');
+  includes('htmlSpan body shows label with @', out, '@X');
+}
+
+if (failures > 0) {
+  // eslint-disable-next-line no-console
+  console.error(`\n${failures} assertion(s) failed.`);
+  process.exit(1);
+} else {
+  // eslint-disable-next-line no-console
+  console.log('\nAll mentionPresets assertions passed.');
+}

package/src/tools/MarkdownEditor/mentionPresets.ts

@@ -0,0 +1,49 @@
+import type { MentionMarkdownRenderer } from './types';
+
+/**
+ * Escape characters that have meaning in markdown link/inline contexts.
+ * Conservative — covers the chars that would break `[text](url)` and
+ * inline emphasis when a label contains them.
+ */
+const escapeMd = (s: string): string => s.replace(/([\\\[\]()_*~`])/g, '\\$1');
+
+/**
+ * Built-in serializers for the `MentionConfig.renderMarkdown` callback.
+ *
+ * Pick one based on what consumes the markdown:
+ *
+ * - LLM / chat composer    → `plainAt`     (the default)
+ * - Plain text export      → `plainLabel`
+ * - Web app with deep-link → `markdownLink(baseUrl)`
+ * - Notion / Linear-style  → `customUri(scheme, kind)`
+ * - Slack-style id refs    → `slackStyle`
+ * - HTML-allowing renderer → `htmlSpan(className?)`
+ *
+ * Or pass a custom function — the type is just `(attrs) => string`.
+ */
+export const mentionPresets = {
+  /** "@Label" — default, ideal for chat where LLMs read the text. */
+  plainAt: (({ label, id }) => `@${label || id}`) as MentionMarkdownRenderer,
+
+  /** "Label" — bare label, no @ prefix. */
+  plainLabel: (({ label, id }) => label || id) as MentionMarkdownRenderer,
+
+  /** "[@Label](baseUrl/id)" — clickable markdown link. */
+  markdownLink: (baseUrl: string): MentionMarkdownRenderer =>
+    ({ label, id }) =>
+      `[@${escapeMd(label || id)}](${baseUrl}${encodeURIComponent(id)})`,
+
+  /** "@[Label](scheme://kind/id)" — Notion / Linear-style custom URI. */
+  customUri: (scheme: string, kind: string): MentionMarkdownRenderer =>
+    ({ label, id }) =>
+      `@[${escapeMd(label || id)}](${scheme}://${kind}/${encodeURIComponent(id)})`,
+
+  /** "<@id>" — Slack-style id-only reference (label dropped — receivers resolve it). */
+  slackStyle: (({ id }) => `<@${id}>`) as MentionMarkdownRenderer,
+
+  /** Inline HTML span — for products that consume markdown with raw HTML allowed. */
+  htmlSpan:
+    (className = 'mention'): MentionMarkdownRenderer =>
+    ({ label, id }) =>
+      `<span class="${className}" data-mention-id="${encodeURIComponent(id)}">@${escapeMd(label || id)}</span>`,
+};

package/src/tools/MarkdownEditor/types.ts

@@ -1,5 +1,3 @@
-import type { ReactNode } from 'react';
-
 /** Item that can be mentioned via @ trigger */
 export interface MentionItem {
   id: string;
@@ -8,6 +6,27 @@ export interface MentionItem {
   thumbnail?: string;
 }
 
+/**
+ * Attributes available when rendering a mention to markdown.
+ *
+ * Same shape Tiptap stores on the `mention` node — `id` is the stable
+ * identifier the suggestion popover injected, `label` is the human text
+ * shown to the user. Either field may be empty if the upstream config
+ * never populated it; renderers should fall back accordingly.
+ */
+export interface MentionAttrs {
+  id: string;
+  label: string;
+}
+
+/**
+ * Function that converts a mention node into its markdown serialization.
+ *
+ * The returned string is what `@tiptap/markdown` writes into the markdown
+ * output of `MarkdownEditor.getMarkdown()`.
+ */
+export type MentionMarkdownRenderer = (attrs: MentionAttrs) => string;
+
 /** Mention configuration */
 export interface MentionConfig {
   /** Trigger character (default: '@') */
@@ -16,4 +35,16 @@ export interface MentionConfig {
   items: MentionItem[];
   /** Max dropdown items (default: 5) */
   maxItems?: number;
+  /**
+   * Custom serializer for mentions when `MarkdownEditor.getMarkdown()` runs.
+   *
+   * Defaults to `mentionPresets.plainAt` which yields `@<label>` (or `@<id>`
+   * when `label` is missing). Use one of `mentionPresets`, or supply your
+   * own function for full control over how mentions appear in the output
+   * markdown string.
+   *
+   * Note: this only affects the *markdown* output. `editor.getText()` and
+   * the rendered DOM still go through `renderText` (`@<label>` by default).
+   */
+  renderMarkdown?: MentionMarkdownRenderer;
 }

package/src/tools/OpenapiViewer/README.md

@@ -251,7 +251,8 @@ interface PlaygroundConfig {
    *  the longread as top-level sections. */
   schemaGrouping?: 'selector' | 'sections';
   /** Sync the active endpoint anchor to ``window.location.hash`` as
-   *  the user scrolls (sections mode). Default: off. */
+   *  the user scrolls (sections mode). Default: on. Pass ``false`` to
+   *  opt out if the host page manages the hash itself. */
   urlSync?: boolean;
 }