@djangocfg/ui-tools 2.1.290 → 2.1.292

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.290",
+  "version": "2.1.292",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -74,7 +74,8 @@
       "import": "./src/tools/CodeEditor/index.ts",
       "require": "./src/tools/CodeEditor/index.ts"
     },
-    "./styles": "./src/styles/index.css"
+    "./styles": "./src/styles/index.css",
+    "./dist.css": "./dist/index.css"
   },
   "files": [
     "dist",
@@ -90,8 +91,8 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.290",
-    "@djangocfg/ui-core": "^2.1.290",
+    "@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",
@@ -101,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",
@@ -138,10 +140,10 @@
     "@maplibre/maplibre-gl-geocoder": "^1.7.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.290",
+    "@djangocfg/i18n": "^2.1.292",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.290",
-    "@djangocfg/ui-core": "^2.1.290",
+    "@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 ──
@@ -47,7 +48,23 @@ export interface MarkdownEditorProps {
   className?: string;
   disabled?: boolean;
   showToolbar?: boolean;
-  /** @mention autocomplete config */
+  /**
+   * `@`-mention autocomplete config.
+   *
+   * IMPORTANT: Tiptap's `useEditor` initialises the editor exactly once.
+   * The `Mention` extension is only registered when `mentions` is truthy
+   * on the FIRST render — handing in a real config later (e.g. after an
+   * async items fetch) silently does nothing, and typing `@` will not
+   * open the popover.
+   *
+   * If you want mentions even with async-loaded items, pass
+   * `{ items: [] }` from the very first render and update the array
+   * when data arrives. Either keep the `MentionConfig` object identity
+   * stable across renders and mutate `items` in place (the suggestion
+   * plugin captures the config by closure and reads `items` on each
+   * query), or accept that swapping the whole object reference is a
+   * no-op for the live editor.
+   */
   mentions?: MentionConfig;
   /** Called when mentioned IDs change */
   onMentionIdsChange?: (ids: string[]) => void;
@@ -68,6 +85,31 @@ export function MarkdownEditor({
 }: MarkdownEditorProps) {
   const isExternalUpdate = useRef(false);
 
+  // ── Dev-mode trap detector ──
+  // Tiptap initialises the editor once with the extensions array from
+  // first render. If `mentions` is undefined on mount and becomes
+  // truthy later, the Mention extension is never installed and the
+  // user-visible @-trigger silently does nothing. Catch this early so
+  // future consumers don't spend hours debugging why @ does nothing.
+  const initialMentionsDefinedRef = useRef<boolean>(mentions !== undefined);
+  const warnedRef = useRef(false);
+  if (
+    process.env.NODE_ENV !== 'production' &&
+    !initialMentionsDefinedRef.current &&
+    mentions !== undefined &&
+    !warnedRef.current
+  ) {
+    warnedRef.current = true;
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[MarkdownEditor] `mentions` flipped from undefined to a config ' +
+        'after mount. Tiptap only installs the Mention extension on first ' +
+        'render — the @-popover will NOT work for this editor instance. ' +
+        'Pass `{ items: [] }` from the very first render and mutate `.items` ' +
+        'in place instead.',
+    );
+  }
+
   const extensions = useMemo(() => {
     const exts: AnyExtension[] = [
       StarterKit.configure({ heading: { levels: [1, 2, 3] } }),
@@ -76,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.');
+}