@thebuoyant-tsdev/mui-ts-library 3.19.0 → 3.20.0

package/README.de.md

@@ -475,6 +475,13 @@ Dieses Projekt folgt [Semantic Versioning](https://semver.org/). In der Praxis b
 
 ## Changelog
 
+### [3.20.0] — 2026-07-09
+
+**Hinzugefügt**
+- `RichTextEditor`: neue Prop `onMentionInserted?: (item: MentionItem) => void` — feuert wenn der Nutzer ein Element aus dem `@`-Mention-Dropdown auswählt. Das vollständige `MentionItem` (`{ id, label }`) wird übergeben — kein HTML-Parsen nötig. Rein additiv. Siehe [Full Changelog](https://github.com/thebuoyant/mui-ts-library/blob/main/CHANGELOG.md) für Details.
+
+---
+
 ### [3.19.0] — 2026-07-08
 
 **Hinzugefügt**

package/README.md

@@ -475,6 +475,13 @@ This project follows [Semantic Versioning](https://semver.org/). In practice:
 
 ## Changelog
 
+### [3.20.0] — 2026-07-09
+
+**Added**
+- `RichTextEditor`: new `onMentionInserted?: (item: MentionItem) => void` prop — fires when the user selects an item from the `@` mention dropdown. The full `MentionItem` (`{ id, label }`) is passed to the callback, so no HTML parsing is needed to track who was mentioned. Purely additive. See [Full Changelog](https://github.com/thebuoyant/mui-ts-library/blob/main/CHANGELOG.md) for details.
+
+---
+
 ### [3.19.0] — 2026-07-08
 
 **Added**

package/dist/components/rich-text-editor/RichTextEditor.d.ts

@@ -5,4 +5,4 @@ declare module "@tiptap/core" {
     }
 }
 import { type RichTextEditorProps } from "./RichTextEditor.types";
-export declare function RichTextEditor({ defaultValue, disabled, error, height, helperText, maxCharacters, mentionItems, mentionTriggerChar, name, onMentionSearch, placeholder, readonly, showCharacterCount, showToolbar, showWordCount, toolbarConfig, translation, value, width, onBlur, onChange, onFocus, onMarkdownChange, onSave, }: RichTextEditorProps): import("react/jsx-runtime").JSX.Element;
+export declare function RichTextEditor({ defaultValue, disabled, error, height, helperText, maxCharacters, mentionItems, mentionTriggerChar, name, onMentionInserted, onMentionSearch, placeholder, readonly, showCharacterCount, showToolbar, showWordCount, toolbarConfig, translation, value, width, onBlur, onChange, onFocus, onMarkdownChange, onSave, }: RichTextEditorProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/rich-text-editor/RichTextEditor.js

@@ -1,40 +1,44 @@
 import { normalizeSize as e } from "../shared/normalizeSize.js";
 import { DEFAULT_RICH_TEXT_EDITOR_TOOLBAR_CONFIG as t, DEFAULT_RICH_TEXT_EDITOR_TRANSLATION as n } from "./RichTextEditor.types.js";
 import { buildMentionSuggestion as r } from "./RichTextEditorMentionSuggestion.js";
-import { RichTextEditorContent as i } from "./RichTextEditorContent.js";
-import { RichTextEditorToolbar as ee } from "./RichTextEditorToolbar.js";
+import { RichTextEditorContent as ee } from "./RichTextEditorContent.js";
+import { RichTextEditorToolbar as i } from "./RichTextEditorToolbar.js";
 import { RichTextEditorFooter as a } from "./RichTextEditorFooter.js";
 import { useEffect as o, useMemo as te, useRef as s, useState as c } from "react";
-import { Box as ne, Divider as re, Paper as ie } from "@mui/material";
-import { Fragment as l, jsx as u, jsxs as d } from "react/jsx-runtime";
-import { useEditor as f } from "@tiptap/react";
+import { Box as l, Divider as u, Paper as ne } from "@mui/material";
+import { Fragment as re, jsx as d, jsxs as f } from "react/jsx-runtime";
+import { useEditor as ie } from "@tiptap/react";
 import { Mention as p } from "@tiptap/extension-mention";
-import { StarterKit as m } from "@tiptap/starter-kit";
-import { TextStyle as ae } from "@tiptap/extension-text-style";
-import { Color as h } from "@tiptap/extension-color";
-import { Highlight as oe } from "@tiptap/extension-highlight";
-import { Placeholder as se } from "@tiptap/extension-placeholder";
-import { CharacterCount as g } from "@tiptap/extension-character-count";
-import { TableKit as _ } from "@tiptap/extension-table";
-import { Image as v } from "@tiptap/extension-image";
-import { Markdown as ce } from "tiptap-markdown";
+import { StarterKit as ae } from "@tiptap/starter-kit";
+import { TextStyle as oe } from "@tiptap/extension-text-style";
+import { Color as se } from "@tiptap/extension-color";
+import { Highlight as ce } from "@tiptap/extension-highlight";
+import { Placeholder as le } from "@tiptap/extension-placeholder";
+import { CharacterCount as m } from "@tiptap/extension-character-count";
+import { TableKit as h } from "@tiptap/extension-table";
+import { Image as g } from "@tiptap/extension-image";
+import { Markdown as _ } from "tiptap-markdown";
 //#region src/components/rich-text-editor/RichTextEditor.tsx
-function y({ defaultValue: y, disabled: b = !1, error: x = !1, height: le, helperText: S, maxCharacters: C, mentionItems: w, mentionTriggerChar: T = "@", name: E, onMentionSearch: D, placeholder: O, readonly: k = !1, showCharacterCount: A = !1, showToolbar: j = !0, showWordCount: M = !1, toolbarConfig: N, translation: P, value: F, width: I, onBlur: L, onChange: R, onFocus: z, onMarkdownChange: B, onSave: V }) {
-	let H = {
+function v({ defaultValue: v, disabled: y = !1, error: b = !1, height: ue, helperText: x, maxCharacters: S, mentionItems: C, mentionTriggerChar: w = "@", name: T, onMentionInserted: E, onMentionSearch: D, placeholder: de, readonly: O = !1, showCharacterCount: k = !1, showToolbar: A = !0, showWordCount: j = !1, toolbarConfig: M, translation: N, value: P, width: F, onBlur: I, onChange: L, onFocus: R, onMarkdownChange: z, onSave: B }) {
+	let V = {
 		...n,
-		...P
-	}, U = {
-		...t,
 		...N
-	}, [W, ue] = c(!1), [G, de] = c(!1), K = s(G), q = s(V), J = s(w ?? []);
+	}, H = {
+		...t,
+		...M
+	}, [U, fe] = c(!1), [W, pe] = c(!1), G = s(W), K = s(B), q = s(C ?? []);
+	o(() => {
+		q.current = C ?? [];
+	}, [C]);
+	let J = s(E);
 	o(() => {
-		J.current = w ?? [];
-	}, [w]), o(() => {
-		K.current = G;
-	}, [G]), o(() => {
-		q.current = V;
-	}, [V]);
-	let Y = e(le), fe = e(I), X = Y === "auto", pe = X ? void 0 : Y ?? 200, Z = w !== void 0 || D !== void 0, Q = te(() => Z ? p.configure({
+		J.current = E;
+	}, [E]), o(() => {
+		G.current = W;
+	}, [W]), o(() => {
+		K.current = B;
+	}, [B]);
+	let Y = e(ue), me = e(F), X = Y === "auto", he = X ? void 0 : Y ?? 200, Z = C !== void 0 || D !== void 0, Q = te(() => Z ? p.configure({
 		HTMLAttributes: { class: "rte-mention" },
 		renderHTML({ options: e, node: t }) {
 			return [
@@ -44,43 +48,44 @@ function y({ defaultValue: y, disabled: b = !1, error: x = !1, height: le, helpe
 					"data-id": t.attrs.id,
 					"data-label": t.attrs.label
 				},
-				`${T}${t.attrs.label}`
+				`${w}${t.attrs.label}`
 			];
 		},
 		suggestion: r({
-			getItems: () => J.current,
+			getItems: () => q.current,
 			onMentionSearch: D,
-			noResultsLabel: H.mentionNoResults ?? "No results"
+			onMentionInserted: (e) => J.current?.(e),
+			noResultsLabel: V.mentionNoResults ?? "No results"
 		})
 	}) : null, [
 		Z,
-		T,
+		w,
 		D
-	]), me = C !== void 0 && C > 0 || A || M, $ = f({
+	]), ge = S !== void 0 && S > 0 || k || j, $ = ie({
 		shouldRerenderOnTransaction: !0,
 		extensions: [
-			m.configure({ link: { openOnClick: !1 } }),
-			ae,
-			h,
-			oe.configure({ multicolor: !0 }),
-			ce.configure({
+			ae.configure({ link: { openOnClick: !1 } }),
+			oe,
+			se,
+			ce.configure({ multicolor: !0 }),
+			_.configure({
 				transformPastedText: !0,
 				transformCopiedText: !1
 			}),
-			se.configure({ placeholder: O ?? "" }),
-			...U.showTableButton ? [_] : [],
-			...U.showImageButton ? [v.configure({
+			le.configure({ placeholder: de ?? "" }),
+			...H.showTableButton ? [h] : [],
+			...H.showImageButton ? [g.configure({
 				inline: !1,
 				allowBase64: !0
 			})] : [],
 			...Q ? [Q] : [],
-			...me ? C !== void 0 && C > 0 ? [g.configure({ limit: C })] : [g] : []
+			...ge ? S !== void 0 && S > 0 ? [m.configure({ limit: S })] : [m] : []
 		],
-		content: F ?? y ?? "",
-		editable: !b && !k,
+		content: P ?? v ?? "",
+		editable: !y && !O,
 		editorProps: {
 			handlePaste(e, t) {
-				if (!K.current) return !1;
+				if (!G.current) return !1;
 				let n = t.clipboardData?.getData("text/plain");
 				if (!n) return !1;
 				t.preventDefault();
@@ -88,31 +93,31 @@ function y({ defaultValue: y, disabled: b = !1, error: x = !1, height: le, helpe
 				return e.dispatch(r.tr.insertText(n, r.selection.from, r.selection.to)), !0;
 			},
 			handleKeyDown(e, t) {
-				return (t.ctrlKey || t.metaKey) && t.key === "s" ? (t.preventDefault(), q.current?.(), !0) : !1;
+				return (t.ctrlKey || t.metaKey) && t.key === "s" ? (t.preventDefault(), K.current?.(), !0) : !1;
 			}
 		},
 		onUpdate({ editor: e }) {
-			R?.(e.getHTML()), B?.(e.storage.markdown.getMarkdown());
+			L?.(e.getHTML()), z?.(e.storage.markdown.getMarkdown());
 		},
 		onBlur() {
-			L?.();
+			I?.();
 		},
 		onFocus() {
-			z?.();
+			R?.();
 		}
 	});
 	o(() => {
-		!$ || F === void 0 || $.getHTML() !== F && $.commands.setContent(F, { emitUpdate: !1 });
-	}, [$, F]), o(() => {
-		$ && $.setEditable(!b && !k);
+		!$ || P === void 0 || $.getHTML() !== P && $.commands.setContent(P, { emitUpdate: !1 });
+	}, [$, P]), o(() => {
+		$ && $.setEditable(!y && !O);
 	}, [
 		$,
-		b,
-		k
+		y,
+		O
 	]);
-	let he = $?.storage.characterCount?.characters?.() ?? 0, ge = $?.storage.characterCount?.words?.() ?? 0, _e = A || C !== void 0 && C > 0 || M || !!S;
-	return /* @__PURE__ */ d(ne, {
-		sx: W ? {
+	let _e = $?.storage.characterCount?.characters?.() ?? 0, ve = $?.storage.characterCount?.words?.() ?? 0, ye = k || S !== void 0 && S > 0 || j || !!x;
+	return /* @__PURE__ */ f(l, {
+		sx: U ? {
 			position: "fixed",
 			top: 0,
 			left: 0,
@@ -124,7 +129,7 @@ function y({ defaultValue: y, disabled: b = !1, error: x = !1, height: le, helpe
 			bgcolor: "background.default",
 			p: 1
 		} : {
-			width: fe ?? "100%",
+			width: me ?? "100%",
 			...X ? {
 				display: "flex",
 				flexDirection: "column",
@@ -132,52 +137,52 @@ function y({ defaultValue: y, disabled: b = !1, error: x = !1, height: le, helpe
 			} : {}
 		},
 		children: [
-			/* @__PURE__ */ d(ie, {
+			/* @__PURE__ */ f(ne, {
 				variant: "outlined",
 				sx: {
 					display: "flex",
 					flexDirection: "column",
 					overflow: "hidden",
-					...W || X ? { flex: 1 } : { height: pe },
-					borderColor: x ? "error.main" : void 0,
+					...U || X ? { flex: 1 } : { height: he },
+					borderColor: b ? "error.main" : void 0,
 					"&:focus-within": {
-						borderColor: x ? "error.main" : "primary.main",
+						borderColor: b ? "error.main" : "primary.main",
 						borderWidth: 2
 					}
 				},
-				children: [j && !k && /* @__PURE__ */ d(l, { children: [/* @__PURE__ */ u(ee, {
+				children: [A && !O && /* @__PURE__ */ f(re, { children: [/* @__PURE__ */ d(i, {
 					editor: $,
-					toolbarConfig: U,
-					translation: H,
-					disabled: b,
-					isFullscreen: W,
-					onToggleFullscreen: () => ue((e) => !e),
-					pasteAsPlainText: G,
-					onTogglePasteAsPlainText: () => de((e) => !e)
-				}), /* @__PURE__ */ u(re, {})] }), /* @__PURE__ */ u(i, {
+					toolbarConfig: H,
+					translation: V,
+					disabled: y,
+					isFullscreen: U,
+					onToggleFullscreen: () => fe((e) => !e),
+					pasteAsPlainText: W,
+					onTogglePasteAsPlainText: () => pe((e) => !e)
+				}), /* @__PURE__ */ d(u, {})] }), /* @__PURE__ */ d(ee, {
 					editor: $,
-					error: x,
-					disabled: b,
-					readonly: k
+					error: b,
+					disabled: y,
+					readonly: O
 				})]
 			}),
-			_e && /* @__PURE__ */ u(a, {
-				helperText: S,
-				error: x,
-				showCharacterCount: A || C !== void 0 && C > 0,
-				charCount: he,
-				maxCharacters: C && C > 0 ? C : void 0,
-				showWordCount: M,
-				wordCount: ge,
-				translation: H
+			ye && /* @__PURE__ */ d(a, {
+				helperText: x,
+				error: b,
+				showCharacterCount: k || S !== void 0 && S > 0,
+				charCount: _e,
+				maxCharacters: S && S > 0 ? S : void 0,
+				showWordCount: j,
+				wordCount: ve,
+				translation: V
 			}),
-			E && /* @__PURE__ */ u("input", {
+			T && /* @__PURE__ */ d("input", {
 				type: "hidden",
-				name: E,
+				name: T,
 				value: $ ? $.getHTML() : ""
 			})
 		]
 	});
 }
 //#endregion
-export { y as RichTextEditor };
+export { v as RichTextEditor };

package/dist/components/rich-text-editor/RichTextEditor.types.d.ts

@@ -147,6 +147,13 @@ export type RichTextEditorProps = {
      * @since 3.14.0
      */
     onMentionSearch?: (query: string) => MentionItem[] | Promise<MentionItem[]>;
+    /**
+     * Called when the user selects a mention item from the autocomplete dropdown.
+     * Fires immediately after the mention node is inserted into the editor.
+     * Useful for tracking which people are mentioned without parsing the HTML output.
+     * @since 3.20.0
+     */
+    onMentionInserted?: (item: MentionItem) => void;
     /**
      * Character that triggers the mention autocomplete popup. Default: "@"
      * @since 3.14.0

package/dist/components/rich-text-editor/RichTextEditorMentionSuggestion.d.ts

@@ -3,7 +3,13 @@ import type { MentionItem } from "./RichTextEditor.types";
 type BuildSuggestionOptions = {
     getItems: () => MentionItem[];
     onMentionSearch?: (query: string) => MentionItem[] | Promise<MentionItem[]>;
+    onMentionInserted?: (item: MentionItem) => void;
     noResultsLabel: string;
 };
-export declare function buildMentionSuggestion({ getItems, onMentionSearch, noResultsLabel, }: BuildSuggestionOptions): Partial<SuggestionOptions<MentionItem>>;
+/** Pure handler factory — extracted for testability without mocking ReactRenderer. */
+export declare function createMentionSelectHandler(command: (attrs: {
+    id: string;
+    label: string;
+}) => void, onMentionInserted?: (item: MentionItem) => void): (item: MentionItem) => void;
+export declare function buildMentionSuggestion({ getItems, onMentionSearch, onMentionInserted, noResultsLabel, }: BuildSuggestionOptions): Partial<SuggestionOptions<MentionItem>>;
 export {};

package/dist/components/rich-text-editor/RichTextEditorMentionSuggestion.js

@@ -1,45 +1,50 @@
 import { RichTextEditorMentionList as e } from "./RichTextEditorMentionList.js";
 import { ReactRenderer as t } from "@tiptap/react";
 //#region src/components/rich-text-editor/RichTextEditorMentionSuggestion.ts
-function n({ getItems: n, onMentionSearch: r, noResultsLabel: i }) {
+function n(e, t) {
+	return (n) => {
+		e({
+			id: n.id,
+			label: n.label
+		}), t?.(n);
+	};
+}
+function r({ getItems: r, onMentionSearch: i, onMentionInserted: a, noResultsLabel: o }) {
 	return {
 		items: async ({ query: e }) => {
-			if (r) return r(e);
-			let t = n(), i = e.toLowerCase();
-			return t.filter((e) => e.label.toLowerCase().includes(i));
+			if (i) return i(e);
+			let t = r(), n = e.toLowerCase();
+			return t.filter((e) => e.label.toLowerCase().includes(n));
 		},
 		render() {
-			let n = null;
+			let r = null;
 			return {
-				onStart(r) {
-					n = new t(e, {
+				onStart(i) {
+					r = new t(e, {
 						props: {
-							items: r.items,
-							noResultsLabel: i,
-							clientRect: r.clientRect,
-							onSelect: (e) => r.command({
-								id: e.id,
-								label: e.label
-							})
+							items: i.items,
+							noResultsLabel: o,
+							clientRect: i.clientRect,
+							onSelect: n(i.command, a)
 						},
-						editor: r.editor
-					}), document.body.appendChild(n.element);
+						editor: i.editor
+					}), document.body.appendChild(r.element);
 				},
 				onUpdate(e) {
-					n?.updateProps({
+					r?.updateProps({
 						items: e.items,
 						clientRect: e.clientRect
 					});
 				},
 				onKeyDown(e) {
-					return e.event.key === "Escape" ? (n?.destroy(), n = null, !0) : n?.ref?.onKeyDown(e.event) ?? !1;
+					return e.event.key === "Escape" ? (r?.destroy(), r = null, !0) : r?.ref?.onKeyDown(e.event) ?? !1;
 				},
 				onExit() {
-					n?.element.remove(), n?.destroy(), n = null;
+					r?.element.remove(), r?.destroy(), r = null;
 				}
 			};
 		}
 	};
 }
 //#endregion
-export { n as buildMentionSuggestion };
+export { r as buildMentionSuggestion };