@djangocfg/ui-tools 2.1.290 → 2.1.291

package/dist/index.d.cts

@@ -2473,7 +2473,23 @@ 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;

package/dist/index.d.ts

@@ -2473,7 +2473,23 @@ 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;

package/dist/index.mjs

@@ -1274,6 +1274,14 @@ function MarkdownEditor({
   onMentionIdsChange
 }) {
   const isExternalUpdate = useRef(false);
+  const initialMentionsDefinedRef = useRef(mentions !== void 0);
+  const warnedRef = useRef(false);
+  if (process.env.NODE_ENV !== "production" && !initialMentionsDefinedRef.current && mentions !== void 0 && !warnedRef.current) {
+    warnedRef.current = true;
+    console.warn(
+      "[MarkdownEditor] `mentions` flipped from undefined to a config after mount. Tiptap only installs the Mention extension on first render \u2014 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 = [
       StarterKit.configure({ heading: { levels: [1, 2, 3] } }),