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

package/README.de.md

@@ -475,6 +475,20 @@ 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**
+- `RichTextEditor`: neue Prop `defaultValue?: string` für unkontrollierten Einsatz — setzt den initialen HTML-Inhalt einmalig beim Mount, kein externer State erforderlich. Analog zu MUI TextFields `defaultValue`. Wenn sowohl `value` als auch `defaultValue` angegeben werden, hat `value` Vorrang. Rein additiv. Siehe [Full Changelog](https://github.com/thebuoyant/mui-ts-library/blob/main/CHANGELOG.md) für Details.
+
+---
+
 ### [3.18.0] — 2026-07-08
 
 **Hinzugefügt**

package/README.md

@@ -475,6 +475,20 @@ 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**
+- `RichTextEditor`: new `defaultValue?: string` prop for uncontrolled usage — sets the initial HTML content once on mount, no external state required. Analogous to MUI TextField's `defaultValue`. When both `value` and `defaultValue` are provided, `value` takes precedence. Purely additive — no existing behaviour changes. See [Full Changelog](https://github.com/thebuoyant/mui-ts-library/blob/main/CHANGELOG.md) for details.
+
+---
+
 ### [3.18.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({ 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 l, Divider as ne, Paper as re } from "@mui/material";
-import { Fragment as u, jsx as d, jsxs as f } from "react/jsx-runtime";
-import { useEditor as p } from "@tiptap/react";
-import { Mention as ie } from "@tiptap/extension-mention";
+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 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 m } from "@tiptap/extension-placeholder";
-import { CharacterCount as h } from "@tiptap/extension-character-count";
-import { TableKit as g } from "@tiptap/extension-table";
-import { Image as _ } from "@tiptap/extension-image";
-import { Markdown as v } from "tiptap-markdown";
+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({ disabled: y = !1, error: b = !1, height: le, helperText: x, maxCharacters: S, mentionItems: C, mentionTriggerChar: w = "@", name: T, onMentionSearch: E, placeholder: D, 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 }) {
+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,
 		...N
 	}, H = {
 		...t,
 		...M
-	}, [U, W] = c(!1), [G, ue] = c(!1), K = s(G), q = s(B), J = s(C ?? []);
+	}, [U, fe] = c(!1), [W, pe] = c(!1), G = s(W), K = s(B), q = s(C ?? []);
 	o(() => {
-		J.current = C ?? [];
-	}, [C]), o(() => {
-		K.current = G;
-	}, [G]), o(() => {
-		q.current = B;
+		q.current = C ?? [];
+	}, [C]);
+	let J = s(E);
+	o(() => {
+		J.current = E;
+	}, [E]), o(() => {
+		G.current = W;
+	}, [W]), o(() => {
+		K.current = B;
 	}, [B]);
-	let Y = e(le), de = e(F), X = Y === "auto", fe = X ? void 0 : Y ?? 200, Z = C !== void 0 || E !== void 0, Q = te(() => Z ? ie.configure({
+	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 [
@@ -48,39 +52,40 @@ function y({ disabled: y = !1, error: b = !1, height: le, helperText: x, maxChar
 			];
 		},
 		suggestion: r({
-			getItems: () => J.current,
-			onMentionSearch: E,
+			getItems: () => q.current,
+			onMentionSearch: D,
+			onMentionInserted: (e) => J.current?.(e),
 			noResultsLabel: V.mentionNoResults ?? "No results"
 		})
 	}) : null, [
 		Z,
 		w,
-		E
-	]), pe = S !== void 0 && S > 0 || k || j, $ = p({
+		D
+	]), ge = S !== void 0 && S > 0 || k || j, $ = ie({
 		shouldRerenderOnTransaction: !0,
 		extensions: [
 			ae.configure({ link: { openOnClick: !1 } }),
 			oe,
 			se,
 			ce.configure({ multicolor: !0 }),
-			v.configure({
+			_.configure({
 				transformPastedText: !0,
 				transformCopiedText: !1
 			}),
-			m.configure({ placeholder: D ?? "" }),
-			...H.showTableButton ? [g] : [],
-			...H.showImageButton ? [_.configure({
+			le.configure({ placeholder: de ?? "" }),
+			...H.showTableButton ? [h] : [],
+			...H.showImageButton ? [g.configure({
 				inline: !1,
 				allowBase64: !0
 			})] : [],
 			...Q ? [Q] : [],
-			...pe ? S !== void 0 && S > 0 ? [h.configure({ limit: S })] : [h] : []
+			...ge ? S !== void 0 && S > 0 ? [m.configure({ limit: S })] : [m] : []
 		],
-		content: P ?? "",
+		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,7 +93,7 @@ function y({ disabled: y = !1, error: b = !1, height: le, helperText: x, maxChar
 				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 }) {
@@ -110,7 +115,7 @@ function y({ disabled: y = !1, error: b = !1, height: le, helperText: x, maxChar
 		y,
 		O
 	]);
-	let me = $?.storage.characterCount?.characters?.() ?? 0, he = $?.storage.characterCount?.words?.() ?? 0, ge = k || S !== void 0 && S > 0 || j || !!x;
+	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",
@@ -124,7 +129,7 @@ function y({ disabled: y = !1, error: b = !1, height: le, helperText: x, maxChar
 			bgcolor: "background.default",
 			p: 1
 		} : {
-			width: de ?? "100%",
+			width: me ?? "100%",
 			...X ? {
 				display: "flex",
 				flexDirection: "column",
@@ -132,43 +137,43 @@ function y({ disabled: y = !1, error: b = !1, height: le, helperText: x, maxChar
 			} : {}
 		},
 		children: [
-			/* @__PURE__ */ f(re, {
+			/* @__PURE__ */ f(ne, {
 				variant: "outlined",
 				sx: {
 					display: "flex",
 					flexDirection: "column",
 					overflow: "hidden",
-					...U || X ? { flex: 1 } : { height: fe },
+					...U || X ? { flex: 1 } : { height: he },
 					borderColor: b ? "error.main" : void 0,
 					"&:focus-within": {
 						borderColor: b ? "error.main" : "primary.main",
 						borderWidth: 2
 					}
 				},
-				children: [A && !O && /* @__PURE__ */ f(u, { children: [/* @__PURE__ */ d(ee, {
+				children: [A && !O && /* @__PURE__ */ f(re, { children: [/* @__PURE__ */ d(i, {
 					editor: $,
 					toolbarConfig: H,
 					translation: V,
 					disabled: y,
 					isFullscreen: U,
-					onToggleFullscreen: () => W((e) => !e),
-					pasteAsPlainText: G,
-					onTogglePasteAsPlainText: () => ue((e) => !e)
-				}), /* @__PURE__ */ d(ne, {})] }), /* @__PURE__ */ d(i, {
+					onToggleFullscreen: () => fe((e) => !e),
+					pasteAsPlainText: W,
+					onTogglePasteAsPlainText: () => pe((e) => !e)
+				}), /* @__PURE__ */ d(u, {})] }), /* @__PURE__ */ d(ee, {
 					editor: $,
 					error: b,
 					disabled: y,
 					readonly: O
 				})]
 			}),
-			ge && /* @__PURE__ */ d(a, {
+			ye && /* @__PURE__ */ d(a, {
 				helperText: x,
 				error: b,
 				showCharacterCount: k || S !== void 0 && S > 0,
-				charCount: me,
+				charCount: _e,
 				maxCharacters: S && S > 0 ? S : void 0,
 				showWordCount: j,
-				wordCount: he,
+				wordCount: ve,
 				translation: V
 			}),
 			T && /* @__PURE__ */ d("input", {
@@ -180,4 +185,4 @@ function y({ disabled: y = !1, error: b = !1, height: le, helperText: x, maxChar
 	});
 }
 //#endregion
-export { y as RichTextEditor };
+export { v as RichTextEditor };

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

@@ -125,6 +125,13 @@ export type RichTextEditorProps = {
     toolbarConfig?: RichTextEditorToolbarConfig;
     translation?: Partial<RichTextEditorTranslation>;
     value?: string;
+    /**
+     * Initial HTML content for uncontrolled usage — set once on mount, never re-synced.
+     * Analogous to MUI TextField's `defaultValue`: the editor manages its own content
+     * after initialisation, no external state required.
+     * When both `value` and `defaultValue` are provided, `value` takes precedence.
+     */
+    defaultValue?: string;
     /** Breite des Editors. Zahlen → px. "auto" oder leer → 100% des Elternelements. */
     width?: number | string;
     /**
@@ -140,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 };