@thebuoyant-tsdev/mui-ts-library 3.13.0 → 3.14.1

package/README.de.md

@@ -434,6 +434,13 @@ Dieses Projekt folgt [Semantic Versioning](https://semver.org/). In der Praxis b
 
 ## Changelog
 
+### [3.14.0] — 2026-07-02
+
+**Hinzugefügt**
+- RichTextEditor: `@`-Mention-Autocomplete (`mentionItems`, `onMentionSearch`, `mentionTriggerChar`, `translation.mentionNoResults`). Dropdown am Cursor verankert, Tastaturnavigation (↑/↓/Enter/Escape), im HTML-Output als `<span data-type="mention" data-id="…">` serialisiert. Neuer Export: `MentionItem`. Neue Peer-Abhängigkeit: `@tiptap/extension-mention`. Siehe [Vollständiger Changelog](https://github.com/thebuoyant/mui-ts-library/blob/main/CHANGELOG.md) für Details.
+
+---
+
 ### [3.13.0] — 2026-06-29
 
 **Hinzugefügt**

package/README.md

@@ -434,6 +434,13 @@ This project follows [Semantic Versioning](https://semver.org/). In practice:
 
 ## Changelog
 
+### [3.14.0] — 2026-07-02
+
+**Added**
+- RichTextEditor: `@`-mention autocomplete (`mentionItems`, `onMentionSearch`, `mentionTriggerChar`, `translation.mentionNoResults`). Dropdown anchored to the cursor, keyboard navigation (↑/↓/Enter/Escape), serialised as `<span data-type="mention" data-id="…">` in HTML output. New export: `MentionItem`. New peer dependency: `@tiptap/extension-mention`. See [Full Changelog](https://github.com/thebuoyant/mui-ts-library/blob/main/CHANGELOG.md) for details.
+
+---
+
 ### [3.13.0] — 2026-06-29
 
 **Added**

package/dist/components/color-picker/ColorPicker.js

@@ -303,8 +303,7 @@ function x({ value: o, onChange: x, onChangeCommitted: S, defaultFormat: ae = "h
 								disabled: T,
 								onChange: (e) => ye(e.target.value),
 								sx: {
-									minWidth: 72,
-									fontSize: "0.75rem",
+									minWidth: 80,
 									flexShrink: 0
 								},
 								children: [

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, name, placeholder, readonly, showCharacterCount, showToolbar, showWordCount, toolbarConfig, translation, value, width, onBlur, onChange, onFocus, onMarkdownChange, }: RichTextEditorProps): import("react/jsx-runtime").JSX.Element;
+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, }: RichTextEditorProps): import("react/jsx-runtime").JSX.Element;

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

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

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

@@ -1,3 +1,7 @@
+export type MentionItem = {
+    id: string;
+    label: string;
+};
 export type RichTextEditorToolbarConfig = {
     showBold?: boolean;
     showItalic?: boolean;
@@ -99,6 +103,8 @@ export type RichTextEditorTranslation = {
     markdownDialogCopy?: string;
     /** @since 3.8.0 */
     markdownDialogCopied?: string;
+    /** Text shown in mention dropdown when no items match the query @since 3.14.0 */
+    mentionNoResults?: string;
 };
 export declare const DEFAULT_RICH_TEXT_EDITOR_TRANSLATION: Required<RichTextEditorTranslation>;
 export type RichTextEditorProps = {
@@ -121,6 +127,24 @@ export type RichTextEditorProps = {
     value?: string;
     /** Breite des Editors. Zahlen → px. "auto" oder leer → 100% des Elternelements. */
     width?: number | string;
+    /**
+     * List of items for @-mention autocomplete. The Mention extension is only active when this prop is provided.
+     * Used for client-side filtering when `onMentionSearch` is not provided.
+     * @since 3.14.0
+     */
+    mentionItems?: MentionItem[];
+    /**
+     * Custom search/filter function called on each keystroke after @.
+     * When provided, `mentionItems` is ignored for filtering — return the relevant subset.
+     * Supports async for server-side search.
+     * @since 3.14.0
+     */
+    onMentionSearch?: (query: string) => MentionItem[] | Promise<MentionItem[]>;
+    /**
+     * Character that triggers the mention autocomplete popup. Default: "@"
+     * @since 3.14.0
+     */
+    mentionTriggerChar?: string;
     onBlur?: () => void;
     onChange?: (value: string) => void;
     onFocus?: () => void;

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

@@ -79,7 +79,8 @@ var e = {
 	markdownDialogApply: "Apply",
 	markdownDialogCancel: "Cancel",
 	markdownDialogCopy: "Copy",
-	markdownDialogCopied: "Copied!"
+	markdownDialogCopied: "Copied!",
+	mentionNoResults: "No results"
 };
 //#endregion
 export { e as DEFAULT_RICH_TEXT_EDITOR_TOOLBAR_CONFIG, t as DEFAULT_RICH_TEXT_EDITOR_TRANSLATION };

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

@@ -0,0 +1,11 @@
+import type { MentionItem } from "./RichTextEditor.types";
+export type MentionListProps = {
+    items: MentionItem[];
+    noResultsLabel: string;
+    clientRect: (() => DOMRect | null) | null;
+    onSelect: (item: MentionItem) => void;
+};
+export type MentionListRef = {
+    onKeyDown: (event: KeyboardEvent) => boolean;
+};
+export declare const RichTextEditorMentionList: import("react").ForwardRefExoticComponent<MentionListProps & import("react").RefAttributes<MentionListRef>>;

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

@@ -0,0 +1,54 @@
+import { forwardRef as e, useEffect as t, useImperativeHandle as n, useRef as r, useState as i } from "react";
+import { List as a, ListItemButton as o, Paper as s, Popper as c, Typography as l } from "@mui/material";
+import { jsx as u } from "react/jsx-runtime";
+//#region src/components/rich-text-editor/RichTextEditorMentionList.tsx
+var d = e(function({ items: e, noResultsLabel: d, clientRect: f, onSelect: p }, m) {
+	let [h, g] = i(0), [_, v] = i(e), y = r(null);
+	e !== _ && (v(e), g(0)), t(() => {
+		(y.current?.children[h])?.scrollIntoView({ block: "nearest" });
+	}, [h]), n(m, () => ({ onKeyDown(t) {
+		return t.key === "ArrowUp" ? (g((t) => (t - 1 + e.length) % e.length), !0) : t.key === "ArrowDown" ? (g((t) => (t + 1) % e.length), !0) : t.key === "Enter" ? (e[h] && p(e[h]), !0) : !1;
+	} }));
+	let b = f ? { getBoundingClientRect: f } : null;
+	return /* @__PURE__ */ u(c, {
+		open: !!b,
+		anchorEl: b,
+		placement: "bottom-start",
+		modifiers: [{
+			name: "offset",
+			options: { offset: [0, 4] }
+		}],
+		style: { zIndex: 1400 },
+		children: /* @__PURE__ */ u(s, {
+			elevation: 4,
+			sx: {
+				maxHeight: 240,
+				overflow: "auto",
+				minWidth: 180
+			},
+			children: e.length === 0 ? /* @__PURE__ */ u(l, {
+				variant: "body2",
+				sx: {
+					px: 2,
+					py: 1,
+					color: "text.secondary"
+				},
+				children: d
+			}) : /* @__PURE__ */ u(a, {
+				ref: y,
+				dense: !0,
+				disablePadding: !0,
+				children: e.map((e, t) => /* @__PURE__ */ u(o, {
+					selected: t === h,
+					onMouseDown: (t) => {
+						t.preventDefault(), p(e);
+					},
+					onMouseEnter: () => g(t),
+					children: e.label
+				}, e.id))
+			})
+		})
+	});
+});
+//#endregion
+export { d as RichTextEditorMentionList };

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

@@ -0,0 +1,9 @@
+import type { SuggestionOptions } from "@tiptap/suggestion";
+import type { MentionItem } from "./RichTextEditor.types";
+type BuildSuggestionOptions = {
+    getItems: () => MentionItem[];
+    onMentionSearch?: (query: string) => MentionItem[] | Promise<MentionItem[]>;
+    noResultsLabel: string;
+};
+export declare function buildMentionSuggestion({ getItems, onMentionSearch, noResultsLabel, }: BuildSuggestionOptions): Partial<SuggestionOptions<MentionItem>>;
+export {};

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

@@ -0,0 +1,45 @@
+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 }) {
+	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));
+		},
+		render() {
+			let n = null;
+			return {
+				onStart(r) {
+					n = new t(e, {
+						props: {
+							items: r.items,
+							noResultsLabel: i,
+							clientRect: r.clientRect,
+							onSelect: (e) => r.command({
+								id: e.id,
+								label: e.label
+							})
+						},
+						editor: r.editor
+					}), document.body.appendChild(n.element);
+				},
+				onUpdate(e) {
+					n?.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;
+				},
+				onExit() {
+					n?.element.remove(), n?.destroy(), n = null;
+				}
+			};
+		}
+	};
+}
+//#endregion
+export { n as buildMentionSuggestion };