@djangocfg/ui-tools 2.1.290 → 2.1.291

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.290",
+  "version": "2.1.291",
   "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.291",
+    "@djangocfg/ui-core": "^2.1.291",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -138,10 +139,10 @@
     "@maplibre/maplibre-gl-geocoder": "^1.7.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.290",
+    "@djangocfg/i18n": "^2.1.291",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.290",
-    "@djangocfg/ui-core": "^2.1.290",
+    "@djangocfg/typescript-config": "^2.1.291",
+    "@djangocfg/ui-core": "^2.1.291",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^24.7.2",

package/src/tools/MarkdownEditor/MarkdownEditor.tsx

@@ -47,7 +47,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 +84,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] } }),