@flikk/ui 1.0.0-beta.3 → 1.0.0-beta.30

package/dist/components/forms/Mention/Mention.js

@@ -1,59 +1,38 @@
+"use client";
+import React__default, { useMemo, useId, useState, useRef, useEffect, useCallback, useLayoutEffect, createElement } from 'react';
 import { jsx, jsxs } from 'react/jsx-runtime';
-import React__default, { useMemo, useState, useRef, useCallback, useEffect, useLayoutEffect } from 'react';
 import { createPortal } from 'react-dom';
 import { AnimatePresence, motion } from 'motion/react';
 import { mentionTheme } from './Mention.theme.js';
 import { cn } from '../../../utils/cn.js';
+import { Avatar } from '../../core/Avatar/Avatar.js';
+import { Tag } from '../../core/Tag/Tag.js';
+import { MenuItem } from '../../core/MenuItem/MenuItem.js';
+import { FormLabel } from '../FormLabel/FormLabel.js';
 import { useIsClient } from '../../../hooks/useIsClient.js';
+import { useSurfaceElevation, SurfaceProvider, surfaceClasses } from '../../../theme/SurfaceContext.js';
+import { normalizeSegments, setCaretAtOffset, getPlainTextOffset, parseDOMToSegments, serializeSegments, serializeSegmentsMasked, insertMentionIntoSegments, MENTION_ATTR } from './Mention.utils.js';
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
-/**
- * Extract the first two initials from a label string.
- */
-const getInitials = (label) => {
-    const parts = label.trim().split(/\s+/);
-    if (parts.length === 1)
-        return parts[0].charAt(0).toUpperCase();
-    return (parts[0].charAt(0) + parts[parts.length - 1].charAt(0)).toUpperCase();
-};
-/**
- * Walk backward from the caret and detect if the user is mid-mention.
- * Returns the active mention context or null.
- */
 const detectActiveMention = (text, caretPos, triggerChars) => {
     if (caretPos === 0)
         return null;
-    // Scan backward from caret to find a trigger character
     for (let i = caretPos - 1; i >= 0; i--) {
         const ch = text[i];
-        // If we hit a whitespace or newline before finding a trigger, stop
-        // UNLESS the character is the very first character after a newline/space
-        // (which means we're looking at a potential trigger at position 0
-        // or right after whitespace).
         if (ch === "\n")
             return null;
         if (triggerChars.includes(ch)) {
-            // The trigger must be at the start of the text or preceded by whitespace
             if (i === 0 || /\s/.test(text[i - 1])) {
                 const query = text.slice(i + 1, caretPos);
-                // Reject if the query contains whitespace (multi-word queries not supported)
-                // Actually, allow spaces in the query for multi-word searches
-                return {
-                    trigger: ch,
-                    query,
-                    startIndex: i,
-                };
+                return { trigger: ch, query, startIndex: i };
             }
             return null;
         }
     }
     return null;
 };
-/**
- * Filter suggestions by a query string (case-insensitive label match).
- */
 const filterSuggestions = (suggestions, query, max) => {
     if (!query)
         return suggestions.slice(0, max);
@@ -63,6 +42,20 @@ const filterSuggestions = (suggestions, query, max) => {
         (s.description && s.description.toLowerCase().includes(lower)))
         .slice(0, max);
 };
+/** Plain-text offset at the start of a given segment index. */
+const getOffsetAtSegment = (segs, segIndex) => {
+    let offset = 0;
+    for (let i = 0; i < segIndex; i++) {
+        const s = segs[i];
+        if (s.type === "text") {
+            offset += s.text.length;
+        }
+        else {
+            offset += s.data.trigger.length + s.data.label.length;
+        }
+    }
+    return offset;
+};
 // ---------------------------------------------------------------------------
 // Dropdown animation
 // ---------------------------------------------------------------------------
@@ -84,14 +77,18 @@ const dropdownVariants = {
 // ---------------------------------------------------------------------------
 // Mention component
 // ---------------------------------------------------------------------------
-const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions: suggestionsProp, onSearch: onSearchProp, value: controlledValue, defaultValue = "", onChange, onMentionSelect, placeholder, size = "md", maxSuggestions = 8, className, wrapperClassName, dropdownClassName, theme: themeOverrides, disabled = false, renderSuggestion, emptyMessage = "No results found", loading = false, rows = 3, ...props }, ref) => {
-    // Merge theme
+const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions: suggestionsProp, onSearch: onSearchProp, value: controlledValue, defaultValue = "", onChange, onMentionSelect, onMentionsChange, placeholder, size = "md", maxSuggestions = 8, className, wrapperClassName, dropdownClassName, theme: themeOverrides, state = "default", disabled = false, helperText, required, label, renderSuggestion, emptyMessage = "No results found", loading = false, mentionTagSize = "sm", mentionTagClassName, mentionTagRemovable = true, rows = 3, style: styleProp, elevation, lift, ...props }, ref) => {
+    // Relative elevation: the suggestion dropdown lifts above its host surface
+    // (overlay base = 5) so a Mention inside a Popover/Modal still reads higher.
+    const surfaceLevel = useSurfaceElevation({ baseRung: 5, offset: 2, elevation, lift });
     const theme = useMemo(() => ({ ...mentionTheme, ...(themeOverrides || {}) }), [themeOverrides]);
-    // Normalize triggers from both APIs
+    const generatedId = useId();
+    const listboxId = `${generatedId}-listbox`;
+    const isDisabled = state === "disabled" || disabled;
+    const isInvalid = state === "invalid";
     const triggers = useMemo(() => {
         if (triggersProp && triggersProp.length > 0)
             return triggersProp;
-        // Simple API: wrap suggestions + onSearch into a single '@' trigger
         return [
             {
                 trigger: "@",
@@ -101,11 +98,24 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
         ];
     }, [triggersProp, suggestionsProp, onSearchProp]);
     const triggerChars = useMemo(() => triggers.map((t) => t.trigger), [triggers]);
-    // Value state (controlled / uncontrolled)
-    const [internalValue, setInternalValue] = useState(defaultValue);
+    // --- Segment model ---
+    const [segments, setSegments] = useState(() => normalizeSegments([{ type: "text", text: defaultValue }]));
+    const mentionMapRef = useRef(new Map());
+    // Controlled mode: if external value diverges, reset segments to plain text
+    const lastSerializedRef = useRef(defaultValue);
     const isControlled = controlledValue !== undefined;
-    const textValue = isControlled ? controlledValue : internalValue;
-    // Focus state for input group styling
+    useEffect(() => {
+        if (isControlled && controlledValue !== lastSerializedRef.current) {
+            // External value changed — reset to plain text
+            const newSegs = normalizeSegments([
+                { type: "text", text: controlledValue },
+            ]);
+            setSegments(newSegs);
+            mentionMapRef.current.clear();
+            lastSerializedRef.current = controlledValue;
+        }
+    }, [isControlled, controlledValue]);
+    // Focus state
     const [isFocused, setIsFocused] = useState(false);
     // Active mention context
     const [activeMention, setActiveMention] = useState(null);
@@ -117,29 +127,48 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
         width: 280,
     });
     // Refs
-    const textareaRef = useRef(null);
+    const editableRef = useRef(null);
     const wrapperRef = useRef(null);
     const dropdownRef = useRef(null);
-    // SSR guard for portal
+    const composingRef = useRef(false);
+    const caretRestoreRef = useRef(null);
+    // Bumped on programmatic structural mutations (mention insert/remove) to
+    // remount the contentEditable so React rebuilds it from `segments` instead
+    // of diffing against a DOM the browser has already restructured. Editing a
+    // contentEditable lets the browser delete/merge/move React-owned nodes
+    // (e.g. backspacing the space before a chip removes its text span); the
+    // next structural reconcile then calls removeChild on a node that is no
+    // longer where React's fiber expects it and throws "removeChild ... not a
+    // child of this node". A full remount sidesteps the partial diff entirely.
+    // NEVER bump on typing — that path reconciles content-only changes safely
+    // and must keep the caret/IME composition stable.
+    const [editorKey, setEditorKey] = useState(0);
+    const lastEditorKeyRef = useRef(0);
+    const remountEditor = useCallback(() => setEditorKey((k) => k + 1), []);
+    // Mirrors the mention count React currently has committed to the DOM. Used
+    // by updateFromDOM to detect when a *browser-handled* edit (range-selection
+    // delete, cut, drag) structurally removed a chip — that desyncs React's
+    // fiber from the DOM, so the next reconcile must be a full remount, not a
+    // partial diff. Synced from `segments` after each commit (below).
+    const renderedMentionCountRef = useRef(0);
+    // Track which segment index is "selected" when clicking a mention tag
+    const [selectedMentionIndex, setSelectedMentionIndex] = useState(null);
     const isClient = useIsClient();
-    // Combine forwarded ref with internal ref
-    const setTextareaRef = useCallback((el) => {
-        textareaRef.current = el;
+    const setEditableRef = useCallback((el) => {
+        editableRef.current = el;
         if (typeof ref === "function") {
             ref(el);
         }
         else if (ref) {
-            ref.current =
-                el;
+            ref.current = el;
         }
     }, [ref]);
-    // Get the current trigger config for the active mention
+    // --- Derived ---
     const activeTriggerConfig = useMemo(() => {
         if (!activeMention)
             return null;
         return triggers.find((t) => t.trigger === activeMention.trigger) || null;
     }, [activeMention, triggers]);
-    // Filtered suggestions for the current query
     const filteredSuggestions = useMemo(() => {
         if (!activeTriggerConfig)
             return [];
@@ -151,93 +180,44 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
         if (!activeMention || !(activeTriggerConfig === null || activeTriggerConfig === void 0 ? void 0 : activeTriggerConfig.onSearch))
             return;
         activeTriggerConfig.onSearch(activeMention.query);
-    }, [activeMention === null || activeMention === void 0 ? void 0 : activeMention.query, activeMention === null || activeMention === void 0 ? void 0 : activeMention.trigger]); // eslint-disable-line react-hooks/exhaustive-deps
+    }, [activeMention === null || activeMention === void 0 ? void 0 : activeMention.query, activeMention === null || activeMention === void 0 ? void 0 : activeMention.trigger, activeTriggerConfig]);
     // Reset highlighted index when suggestions change
     useEffect(() => {
         setHighlightedIndex(filteredSuggestions.length > 0 ? 0 : -1);
     }, [filteredSuggestions.length, activeMention === null || activeMention === void 0 ? void 0 : activeMention.query]);
-    // -----------------------------------------------------------------------
-    // Dropdown positioning via caret coordinates
-    // -----------------------------------------------------------------------
-    /**
-     * Calculate the pixel coordinates of the caret inside the textarea using
-     * a hidden mirror div. This is the standard technique for textarea caret
-     * positioning since browsers don't expose it natively.
-     */
-    const measureCaretPosition = useCallback(() => {
-        var _a;
-        const textarea = textareaRef.current;
-        if (!textarea)
-            return null;
-        const mirror = document.createElement("div");
-        const computed = window.getComputedStyle(textarea);
-        // Copy all relevant styles so that text wraps identically
-        const stylesToCopy = [
-            "fontFamily",
-            "fontSize",
-            "fontWeight",
-            "fontStyle",
-            "letterSpacing",
-            "textTransform",
-            "wordSpacing",
-            "textIndent",
-            "whiteSpace",
-            "wordWrap",
-            "overflowWrap",
-            "lineHeight",
-            "paddingTop",
-            "paddingRight",
-            "paddingBottom",
-            "paddingLeft",
-            "borderTopWidth",
-            "borderRightWidth",
-            "borderBottomWidth",
-            "borderLeftWidth",
-            "boxSizing",
-        ];
-        mirror.style.position = "absolute";
-        mirror.style.top = "0";
-        mirror.style.left = "-9999px";
-        mirror.style.visibility = "hidden";
-        mirror.style.overflow = "hidden";
-        mirror.style.width = `${textarea.offsetWidth}px`;
-        for (const prop of stylesToCopy) {
-            mirror.style[prop] = computed.getPropertyValue(prop.replace(/([A-Z])/g, "-$1").toLowerCase());
-        }
-        // Text up to the caret
-        const caretPos = (_a = textarea.selectionStart) !== null && _a !== void 0 ? _a : 0;
-        const textBefore = textarea.value.substring(0, caretPos);
-        // Replace spaces with non-breaking spaces so whitespace is preserved
-        mirror.textContent = textBefore.replace(/ /g, "\u00a0");
-        // Place a span at the caret position to measure its coordinates
-        const caretSpan = document.createElement("span");
-        caretSpan.textContent = "\u200b"; // zero-width space
-        mirror.appendChild(caretSpan);
-        document.body.appendChild(mirror);
-        const spanRect = caretSpan.getBoundingClientRect();
-        const textareaRect = textarea.getBoundingClientRect();
-        // The span position is in the mirror; we need to offset by the textarea's
-        // actual position and account for scrollTop.
-        const relativeTop = spanRect.top - mirror.getBoundingClientRect().top - textarea.scrollTop;
-        const relativeLeft = spanRect.left - mirror.getBoundingClientRect().left;
-        document.body.removeChild(mirror);
-        return {
-            top: textareaRect.top + relativeTop,
-            left: textareaRect.left + relativeLeft,
-        };
-    }, []);
+    // --- Notify onMentionsChange ---
+    const notifyMentionsChange = useCallback((segs) => {
+        if (!onMentionsChange)
+            return;
+        const mentions = segs
+            .filter((s) => s.type === "mention")
+            .map((s) => s.data);
+        onMentionsChange(mentions);
+    }, [onMentionsChange]);
+    // --- Dropdown positioning via Range API ---
     const updateDropdownPosition = useCallback(() => {
-        const pos = measureCaretPosition();
-        if (!pos)
+        const sel = window.getSelection();
+        if (!sel || sel.rangeCount === 0 || !editableRef.current)
+            return;
+        const range = sel.getRangeAt(0).cloneRange();
+        range.collapse(true);
+        const rect = range.getBoundingClientRect();
+        // Fallback if rect is zero (e.g. empty container)
+        if (rect.top === 0 && rect.left === 0) {
+            const containerRect = editableRef.current.getBoundingClientRect();
+            setDropdownPos({
+                top: containerRect.bottom + 4,
+                left: containerRect.left,
+                width: 280,
+            });
             return;
-        const lineHeight = parseFloat(window.getComputedStyle(textareaRef.current).lineHeight || "20");
+        }
         setDropdownPos({
-            top: pos.top + lineHeight + 4,
-            left: pos.left,
+            top: rect.bottom + 4,
+            left: rect.left,
             width: 280,
         });
-    }, [measureCaretPosition]);
-    // Reposition dropdown whenever the active mention changes
+    }, []);
     useLayoutEffect(() => {
         if (activeMention) {
             updateDropdownPosition();
@@ -258,99 +238,351 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
             window.removeEventListener("resize", handleReposition);
         };
     }, [isDropdownOpen, updateDropdownPosition]);
-    // -----------------------------------------------------------------------
     // Click outside to close dropdown
-    // -----------------------------------------------------------------------
     useEffect(() => {
         if (!isDropdownOpen)
             return;
         const handleClickOutside = (e) => {
             if (dropdownRef.current &&
                 !dropdownRef.current.contains(e.target) &&
-                textareaRef.current &&
-                !textareaRef.current.contains(e.target)) {
+                editableRef.current &&
+                !editableRef.current.contains(e.target)) {
                 setActiveMention(null);
             }
         };
         document.addEventListener("mousedown", handleClickOutside);
         return () => document.removeEventListener("mousedown", handleClickOutside);
     }, [isDropdownOpen]);
-    // -----------------------------------------------------------------------
-    // Handlers
-    // -----------------------------------------------------------------------
-    const setValue = useCallback((newValue) => {
-        if (!isControlled) {
-            setInternalValue(newValue);
+    // --- DOM cleanup & caret restore after React re-render ---
+    useLayoutEffect(() => {
+        const el = editableRef.current;
+        if (!el || composingRef.current)
+            return;
+        // Remove stray text nodes that are direct children of the container.
+        // Browser contentEditable can insert characters as direct text children
+        // instead of inside our React-managed <span> elements. These stray nodes
+        // cause text duplication when parseDOMToSegments reads them alongside
+        // the span content on the next input event.
+        for (let i = el.childNodes.length - 1; i >= 0; i--) {
+            const child = el.childNodes[i];
+            if (child.nodeType === Node.TEXT_NODE) {
+                el.removeChild(child);
+            }
         }
-        onChange === null || onChange === void 0 ? void 0 : onChange(newValue);
-    }, [isControlled, onChange]);
-    const handleChange = useCallback((e) => {
-        var _a;
-        const newValue = e.target.value;
-        setValue(newValue);
-        // Detect active mention from the caret position
-        const caretPos = (_a = e.target.selectionStart) !== null && _a !== void 0 ? _a : newValue.length;
-        const mention = detectActiveMention(newValue, caretPos, triggerChars);
-        setActiveMention(mention);
-    }, [setValue, triggerChars]);
-    const handleSelect = useCallback((e) => {
-        var _a;
-        // When the caret moves (click, arrow keys), recheck for active mention
-        const textarea = e.currentTarget;
-        const caretPos = (_a = textarea.selectionStart) !== null && _a !== void 0 ? _a : 0;
-        const mention = detectActiveMention(textarea.value, caretPos, triggerChars);
-        setActiveMention(mention);
-    }, [triggerChars]);
+        if (caretRestoreRef.current !== null) {
+            // A structural mutation remounts the editable div (see `editorKey`),
+            // which drops DOM focus. Re-focus before restoring the caret so the
+            // user can keep typing seamlessly after inserting/removing a mention.
+            if (editorKey !== lastEditorKeyRef.current && document.activeElement !== el) {
+                el.focus({ preventScroll: true });
+            }
+            setCaretAtOffset(el, caretRestoreRef.current);
+            caretRestoreRef.current = null;
+        }
+        lastEditorKeyRef.current = editorKey;
+    });
+    // Keep the committed-mention-count ref in sync so updateFromDOM can detect
+    // a browser-removed chip on the next edit (see renderedMentionCountRef).
+    useEffect(() => {
+        renderedMentionCountRef.current = segments.filter((s) => s.type === "mention").length;
+    }, [segments]);
+    // --- Handlers ---
+    const updateFromDOM = useCallback(() => {
+        if (!editableRef.current || composingRef.current)
+            return;
+        // Save caret position BEFORE triggering re-render
+        const offset = getPlainTextOffset(editableRef.current);
+        const newSegs = parseDOMToSegments(editableRef.current, mentionMapRef.current);
+        const serialized = serializeSegments(newSegs);
+        // Restore caret after React re-renders the contentEditable
+        if (offset !== null) {
+            caretRestoreRef.current = offset;
+        }
+        // If a browser-handled edit (range-selection delete, cut, drag) removed a
+        // chip, the DOM no longer matches React's fiber. A content-only reconcile
+        // would then call removeChild on an already-gone node and throw, so force
+        // a full remount instead. Pure text edits keep the count stable and
+        // reconcile normally — preserving caret/IME.
+        const newMentionCount = newSegs.filter((s) => s.type === "mention").length;
+        if (newMentionCount !== renderedMentionCountRef.current) {
+            remountEditor();
+        }
+        setSegments(newSegs);
+        lastSerializedRef.current = serialized;
+        onChange === null || onChange === void 0 ? void 0 : onChange(serialized);
+        notifyMentionsChange(newSegs);
+        // Detect active mention using masked text (hides @ from existing mentions)
+        if (offset !== null) {
+            const maskedText = serializeSegmentsMasked(newSegs);
+            const mention = detectActiveMention(maskedText, offset, triggerChars);
+            setActiveMention(mention);
+        }
+    }, [onChange, triggerChars, notifyMentionsChange, remountEditor]);
+    const handleInput = useCallback(() => {
+        setSelectedMentionIndex(null);
+        updateFromDOM();
+    }, [updateFromDOM]);
+    const handleSelect = useCallback(() => {
+        if (!editableRef.current || composingRef.current)
+            return;
+        const offset = getPlainTextOffset(editableRef.current);
+        if (offset !== null) {
+            const maskedText = serializeSegmentsMasked(segments);
+            const mention = detectActiveMention(maskedText, offset, triggerChars);
+            setActiveMention(mention);
+        }
+    }, [segments, triggerChars]);
     const insertMention = useCallback((suggestion) => {
-        if (!activeMention || !textareaRef.current)
+        if (!activeMention || !editableRef.current)
             return;
         const { trigger, startIndex, query } = activeMention;
-        const before = textValue.slice(0, startIndex);
-        const after = textValue.slice(startIndex + 1 + query.length); // +1 for trigger char
-        const insertText = `${trigger}${suggestion.label} `;
-        const newValue = before + insertText + after;
-        setValue(newValue);
+        const replaceLength = 1 + query.length; // trigger + query
+        const mentionData = {
+            id: suggestion.id,
+            label: suggestion.label,
+            trigger,
+            avatar: suggestion.avatar,
+        };
+        // Store in mention map for DOM parsing
+        mentionMapRef.current.set(suggestion.id, mentionData);
+        const newSegs = insertMentionIntoSegments(segments, mentionData, startIndex, replaceLength);
+        const serialized = serializeSegments(newSegs);
+        lastSerializedRef.current = serialized;
+        // Calculate where caret should go: after trigger+label+space
+        const caretPos = startIndex + trigger.length + suggestion.label.length + 1;
+        caretRestoreRef.current = caretPos;
+        setSegments(newSegs);
         setActiveMention(null);
         setHighlightedIndex(-1);
+        remountEditor();
+        onChange === null || onChange === void 0 ? void 0 : onChange(serialized);
+        notifyMentionsChange(newSegs);
         onMentionSelect === null || onMentionSelect === void 0 ? void 0 : onMentionSelect(suggestion, trigger);
-        // Move the caret to after the inserted mention
-        const newCaretPos = before.length + insertText.length;
-        requestAnimationFrame(() => {
-            if (textareaRef.current) {
-                textareaRef.current.focus();
-                textareaRef.current.selectionStart = newCaretPos;
-                textareaRef.current.selectionEnd = newCaretPos;
+    }, [
+        activeMention,
+        segments,
+        onChange,
+        onMentionSelect,
+        notifyMentionsChange,
+        remountEditor,
+    ]);
+    // Map a mention DOM element back to its segment index. The chips are
+    // React-rendered, so we locate the element among all mention nodes and
+    // translate that position into the nth "mention" segment.
+    const segmentIndexForMentionEl = useCallback((mentionEl) => {
+        if (!editableRef.current)
+            return -1;
+        const allMentions = editableRef.current.querySelectorAll(`[${MENTION_ATTR}]`);
+        const domIdx = Array.from(allMentions).indexOf(mentionEl);
+        if (domIdx === -1)
+            return -1;
+        let count = 0;
+        for (let i = 0; i < segments.length; i++) {
+            if (segments[i].type === "mention") {
+                if (count === domIdx)
+                    return i;
+                count++;
             }
-        });
-    }, [activeMention, textValue, setValue, onMentionSelect]);
+        }
+        return -1;
+    }, [segments]);
+    // Remove a mention via the segment model — NEVER by mutating the DOM.
+    // The chips are React-owned nodes; calling removeChild() on them directly
+    // desyncs React's fiber tree from the DOM and makes the next reconcile
+    // throw "removeChild ... not a child of this node". Splicing the segment
+    // and letting React drop the node keeps React the sole DOM owner. The
+    // caret lands at the gap the mention left (its segment start offset).
+    const removeMentionSegment = useCallback((segIndex) => {
+        const newSegs = normalizeSegments([
+            ...segments.slice(0, segIndex),
+            ...segments.slice(segIndex + 1),
+        ]);
+        caretRestoreRef.current = getOffsetAtSegment(segments, segIndex);
+        const serialized = serializeSegments(newSegs);
+        lastSerializedRef.current = serialized;
+        setSegments(newSegs);
+        setSelectedMentionIndex(null);
+        setActiveMention(null);
+        remountEditor();
+        onChange === null || onChange === void 0 ? void 0 : onChange(serialized);
+        notifyMentionsChange(newSegs);
+    }, [segments, onChange, notifyMentionsChange, remountEditor]);
     const handleKeyDown = useCallback((e) => {
-        if (!isDropdownOpen)
-            return;
-        switch (e.key) {
-            case "ArrowDown":
+        var _a;
+        // --- Selected mention: delete / replace / deselect ---
+        if (selectedMentionIndex !== null &&
+            ((_a = segments[selectedMentionIndex]) === null || _a === void 0 ? void 0 : _a.type) === "mention") {
+            if (e.key === "Backspace" || e.key === "Delete") {
                 e.preventDefault();
-                setHighlightedIndex((prev) => prev >= filteredSuggestions.length - 1 ? 0 : prev + 1);
-                break;
-            case "ArrowUp":
+                const newSegs = normalizeSegments([
+                    ...segments.slice(0, selectedMentionIndex),
+                    ...segments.slice(selectedMentionIndex + 1),
+                ]);
+                caretRestoreRef.current = getOffsetAtSegment(segments, selectedMentionIndex);
+                const serialized = serializeSegments(newSegs);
+                lastSerializedRef.current = serialized;
+                setSegments(newSegs);
+                setSelectedMentionIndex(null);
+                remountEditor();
+                onChange === null || onChange === void 0 ? void 0 : onChange(serialized);
+                notifyMentionsChange(newSegs);
+                return;
+            }
+            // Printable character → remove mention and insert the character
+            if (e.key.length === 1 && !e.ctrlKey && !e.metaKey) {
                 e.preventDefault();
-                setHighlightedIndex((prev) => prev <= 0 ? filteredSuggestions.length - 1 : prev - 1);
-                break;
-            case "Enter":
-                if (highlightedIndex >= 0 && highlightedIndex < filteredSuggestions.length) {
+                const newSegs = normalizeSegments([
+                    ...segments.slice(0, selectedMentionIndex),
+                    { type: "text", text: e.key },
+                    ...segments.slice(selectedMentionIndex + 1),
+                ]);
+                caretRestoreRef.current =
+                    getOffsetAtSegment(segments, selectedMentionIndex) + 1;
+                const serialized = serializeSegments(newSegs);
+                lastSerializedRef.current = serialized;
+                setSegments(newSegs);
+                setSelectedMentionIndex(null);
+                remountEditor();
+                onChange === null || onChange === void 0 ? void 0 : onChange(serialized);
+                notifyMentionsChange(newSegs);
+                return;
+            }
+            // Arrow keys / Escape → just deselect
+            if (e.key.startsWith("Arrow") || e.key === "Escape") {
+                setSelectedMentionIndex(null);
+                return;
+            }
+        }
+        // --- Dropdown navigation ---
+        if (isDropdownOpen) {
+            switch (e.key) {
+                case "ArrowDown":
+                    e.preventDefault();
+                    setHighlightedIndex((prev) => prev >= filteredSuggestions.length - 1 ? 0 : prev + 1);
+                    return;
+                case "ArrowUp":
+                    e.preventDefault();
+                    setHighlightedIndex((prev) => prev <= 0 ? filteredSuggestions.length - 1 : prev - 1);
+                    return;
+                case "Enter":
+                    if (highlightedIndex >= 0 &&
+                        highlightedIndex < filteredSuggestions.length) {
+                        e.preventDefault();
+                        insertMention(filteredSuggestions[highlightedIndex]);
+                    }
+                    return;
+                case "Escape":
                     e.preventDefault();
-                    insertMention(filteredSuggestions[highlightedIndex]);
+                    setActiveMention(null);
+                    return;
+                case "Tab":
+                    setActiveMention(null);
+                    return;
+            }
+        }
+        // --- Backspace into mention (atomic delete) ---
+        if (e.key === "Backspace" && editableRef.current) {
+            const sel = window.getSelection();
+            if (!sel || sel.rangeCount === 0)
+                return;
+            const range = sel.getRangeAt(0);
+            if (!range.collapsed)
+                return; // Let browser handle selection delete
+            const { startContainer, startOffset } = range;
+            // Case 1: Caret in a text node at offset 0, previous sibling is a mention
+            if (startContainer.nodeType === Node.TEXT_NODE && startOffset === 0) {
+                const prevSibling = startContainer.previousSibling;
+                if (prevSibling &&
+                    prevSibling.nodeType === Node.ELEMENT_NODE &&
+                    prevSibling.hasAttribute(MENTION_ATTR)) {
+                    const segIdx = segmentIndexForMentionEl(prevSibling);
+                    if (segIdx !== -1) {
+                        e.preventDefault();
+                        removeMentionSegment(segIdx);
+                        return;
+                    }
                 }
-                break;
-            case "Escape":
-                e.preventDefault();
-                setActiveMention(null);
-                break;
-            case "Tab":
-                // Close dropdown on tab without preventing default
-                setActiveMention(null);
-                break;
+            }
+            // Case 2: Caret in parent element, child before offset is a mention
+            if (startContainer.nodeType === Node.ELEMENT_NODE &&
+                startOffset > 0) {
+                const children = Array.from(startContainer.childNodes);
+                const prevChild = children[startOffset - 1];
+                if (prevChild &&
+                    prevChild.nodeType === Node.ELEMENT_NODE &&
+                    prevChild.hasAttribute(MENTION_ATTR)) {
+                    const segIdx = segmentIndexForMentionEl(prevChild);
+                    if (segIdx !== -1) {
+                        e.preventDefault();
+                        removeMentionSegment(segIdx);
+                        return;
+                    }
+                }
+            }
+        }
+        // --- Delete into mention (atomic delete) ---
+        if (e.key === "Delete" && editableRef.current) {
+            const sel = window.getSelection();
+            if (!sel || sel.rangeCount === 0)
+                return;
+            const range = sel.getRangeAt(0);
+            if (!range.collapsed)
+                return;
+            const { startContainer, startOffset } = range;
+            if (startContainer.nodeType === Node.TEXT_NODE) {
+                const textLen = (startContainer.textContent || "").length;
+                if (startOffset === textLen) {
+                    const nextSibling = startContainer.nextSibling;
+                    if (nextSibling &&
+                        nextSibling.nodeType === Node.ELEMENT_NODE &&
+                        nextSibling.hasAttribute(MENTION_ATTR)) {
+                        const segIdx = segmentIndexForMentionEl(nextSibling);
+                        if (segIdx !== -1) {
+                            e.preventDefault();
+                            removeMentionSegment(segIdx);
+                            return;
+                        }
+                    }
+                }
+            }
+            if (startContainer.nodeType === Node.ELEMENT_NODE) {
+                const children = Array.from(startContainer.childNodes);
+                const nextChild = children[startOffset];
+                if (nextChild &&
+                    nextChild.nodeType === Node.ELEMENT_NODE &&
+                    nextChild.hasAttribute(MENTION_ATTR)) {
+                    const segIdx = segmentIndexForMentionEl(nextChild);
+                    if (segIdx !== -1) {
+                        e.preventDefault();
+                        removeMentionSegment(segIdx);
+                        return;
+                    }
+                }
+            }
+        }
+        // Prevent Enter from creating <div> - insert <br> or \n instead
+        if (e.key === "Enter" && !e.shiftKey && !isDropdownOpen) {
+            e.preventDefault();
+            document.execCommand("insertLineBreak");
         }
-    }, [isDropdownOpen, highlightedIndex, filteredSuggestions, insertMention]);
+    }, [
+        isDropdownOpen,
+        highlightedIndex,
+        filteredSuggestions,
+        insertMention,
+        segmentIndexForMentionEl,
+        removeMentionSegment,
+        remountEditor,
+        selectedMentionIndex,
+        segments,
+        onChange,
+        notifyMentionsChange,
+    ]);
+    const handlePaste = useCallback((e) => {
+        e.preventDefault();
+        const text = e.clipboardData.getData("text/plain");
+        document.execCommand("insertText", false, text);
+    }, []);
     const handleFocus = useCallback((e) => {
         var _a;
         setIsFocused(true);
@@ -358,9 +590,29 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
     }, [props.onFocus]);
     const handleBlur = useCallback((e) => {
         var _a;
+        setSelectedMentionIndex(null);
         setIsFocused(false);
         (_a = props.onBlur) === null || _a === void 0 ? void 0 : _a.call(props, e);
     }, [props.onBlur]);
+    const handleCompositionStart = useCallback(() => {
+        composingRef.current = true;
+    }, []);
+    const handleCompositionEnd = useCallback(() => {
+        composingRef.current = false;
+        updateFromDOM();
+    }, [updateFromDOM]);
+    // Click on a mention tag → mark its segment index as selected
+    const handleClick = useCallback((e) => {
+        var _a;
+        const target = e.target;
+        const mentionEl = (_a = target.closest) === null || _a === void 0 ? void 0 : _a.call(target, `[${MENTION_ATTR}]`);
+        if (!mentionEl || !editableRef.current) {
+            setSelectedMentionIndex(null);
+            return;
+        }
+        const segIdx = segmentIndexForMentionEl(mentionEl);
+        setSelectedMentionIndex(segIdx === -1 ? null : segIdx);
+    }, [segmentIndexForMentionEl]);
     // Scroll highlighted suggestion into view
     useEffect(() => {
         if (highlightedIndex >= 0 && dropdownRef.current) {
@@ -370,28 +622,72 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
             }
         }
     }, [highlightedIndex]);
+    // --- Check if content is empty for placeholder ---
+    const isContentEmpty = useMemo(() => {
+        return segments.every((s) => s.type === "text" && s.text === "");
+    }, [segments]);
+    // -----------------------------------------------------------------------
+    // Render segments as React children
+    // -----------------------------------------------------------------------
+    const renderedSegments = useMemo(() => {
+        return segments.map((seg, i) => {
+            if (seg.type === "text") {
+                return (jsx("span", { "data-segment": "text", children: seg.text }, `text-${i}`));
+            }
+            return (jsx(Tag, { size: mentionTagSize, removable: mentionTagRemovable, 
+                // Route removal through the segment model (same path as keyboard
+                // delete) so React stays the DOM owner and the editor remounts
+                // cleanly. stopPropagation in Tag keeps this click from also
+                // selecting the chip via the editable's onClick.
+                onRemove: () => removeMentionSegment(i), animated: false, 
+                // Always pass the avatar object (src may be undefined) so the chip
+                // shows the initials fallback when no photo is available — matching
+                // the suggestion dropdown. Avatar renders the first initial at xs.
+                avatar: { src: seg.data.avatar, name: seg.data.label }, contentEditable: false, className: cn(
+                // align-middle: avatar vs text-only chips have differing intrinsic
+                // heights and an inline-flex baseline is ill-defined, so center on
+                // the line's middle to keep every chip level when used inline.
+                "align-middle", i === selectedMentionIndex &&
+                    "ring-2 ring-[var(--color-primary)] ring-offset-1", mentionTagClassName), [MENTION_ATTR]: seg.data.id,
+                "data-mention-label": seg.data.label,
+                "data-mention-trigger": seg.data.trigger, children: seg.data.label }, `mention-${seg.data.id}-${i}`));
+        });
+    }, [
+        segments,
+        mentionTagSize,
+        mentionTagClassName,
+        mentionTagRemovable,
+        removeMentionSegment,
+        selectedMentionIndex,
+    ]);
     // -----------------------------------------------------------------------
     // Render suggestion item
     // -----------------------------------------------------------------------
     const renderSuggestionItem = (suggestion, index) => {
         const isHighlighted = index === highlightedIndex;
         const triggerChar = (activeMention === null || activeMention === void 0 ? void 0 : activeMention.trigger) || "@";
-        // Custom renderer
         if (renderSuggestion) {
             return (jsx("div", { role: "option", "aria-selected": isHighlighted, "data-suggestion-index": index, className: cn(theme.suggestionStyle, isHighlighted && theme.suggestionHighlightedStyle), onMouseEnter: () => setHighlightedIndex(index), onMouseDown: (e) => {
-                    e.preventDefault(); // Prevent textarea blur
+                    e.preventDefault();
                     insertMention(suggestion);
                 }, children: renderSuggestion(suggestion, isHighlighted, triggerChar) }, suggestion.id));
         }
-        return (jsxs("div", { role: "option", "aria-selected": isHighlighted, "data-suggestion-index": index, className: cn(theme.suggestionStyle, isHighlighted && theme.suggestionHighlightedStyle), onMouseEnter: () => setHighlightedIndex(index), onMouseDown: (e) => {
-                e.preventDefault(); // Prevent textarea blur
+        return (jsx(MenuItem, { role: "option", "aria-selected": isHighlighted, "data-suggestion-index": index, 
+            // Drives MenuItem's selected styling; highlight follows keyboard nav
+            // (and hover, via onMouseEnter setting highlightedIndex).
+            selected: isHighlighted, startContent: jsx(Avatar, { src: suggestion.avatar, name: suggestion.label, size: "xs", className: "ring-0 border-0" }), subtitle: suggestion.description, onMouseEnter: () => setHighlightedIndex(index), 
+            // mousedown + preventDefault keeps focus in the contentEditable so
+            // selecting a suggestion never blurs the editor (MenuItem's onClick/
+            // onActivate path would fire too late, after focus moves).
+            onMouseDown: (e) => {
+                e.preventDefault();
                 insertMention(suggestion);
-            }, children: [suggestion.avatar ? (jsx("img", { src: suggestion.avatar, alt: suggestion.label, className: theme.suggestionAvatarStyle })) : (jsx("div", { className: theme.suggestionAvatarFallbackStyle, children: getInitials(suggestion.label) })), jsxs("div", { className: "flex flex-col min-w-0", children: [jsx("span", { className: theme.suggestionLabelStyle, children: suggestion.label }), suggestion.description && (jsx("span", { className: theme.suggestionDescriptionStyle, children: suggestion.description }))] })] }, suggestion.id));
+            }, children: suggestion.label }, suggestion.id));
     };
     // -----------------------------------------------------------------------
     // Dropdown portal content
     // -----------------------------------------------------------------------
-    const dropdownContent = (jsx(AnimatePresence, { mode: "wait", children: isDropdownOpen && (jsx(motion.div, { ref: dropdownRef, role: "listbox", "aria-label": "Suggestions", className: cn(theme.dropdownStyle, dropdownClassName), style: {
+    const dropdownContent = (jsx(AnimatePresence, { mode: "wait", children: isDropdownOpen && (jsx(motion.div, { ref: dropdownRef, id: listboxId, "data-flikkui-portal": "", role: "listbox", "aria-label": "Suggestions", className: cn(surfaceClasses(surfaceLevel, { translucent: true }), theme.dropdownStyle, dropdownClassName), style: {
                 position: "fixed",
                 top: `${dropdownPos.top}px`,
                 left: `${dropdownPos.left}px`,
@@ -399,11 +695,21 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
                 maxWidth: "360px",
                 zIndex: 1000,
                 overscrollBehavior: "contain",
-            }, variants: dropdownVariants, initial: "initial", animate: "visible", exit: "exit", children: loading ? (jsx("div", { className: theme.loadingStyle, children: "Searching..." })) : filteredSuggestions.length === 0 ? (jsx("div", { className: theme.emptyMessageStyle, children: emptyMessage })) : (filteredSuggestions.map((suggestion, index) => renderSuggestionItem(suggestion, index))) })) }));
+            }, variants: dropdownVariants, initial: "initial", animate: "visible", exit: "exit", children: jsx(SurfaceProvider, { level: surfaceLevel, children: loading ? (jsx("div", { className: theme.loadingStyle, children: "Searching..." })) : filteredSuggestions.length === 0 ? (jsx("div", { className: theme.emptyMessageStyle, children: emptyMessage })) : (filteredSuggestions.map((suggestion, index) => renderSuggestionItem(suggestion, index))) }) })) }));
     // -----------------------------------------------------------------------
     // Render
     // -----------------------------------------------------------------------
-    return (jsxs("div", { className: cn(theme.wrapperStyle, wrapperClassName), children: [jsx("div", { ref: wrapperRef, className: cn(theme.inputGroupStyle, isFocused && theme.inputGroupFocusStyle), children: jsx("textarea", { ref: setTextareaRef, value: textValue, onChange: handleChange, onSelect: handleSelect, onKeyDown: handleKeyDown, onFocus: handleFocus, onBlur: handleBlur, placeholder: placeholder, disabled: disabled, rows: rows, role: "textbox", "aria-multiline": "true", "aria-autocomplete": "list", "aria-expanded": isDropdownOpen, "aria-haspopup": "listbox", className: cn(theme.textareaStyle, theme.sizes[size], className), ...props }) }), isClient && createPortal(dropdownContent, document.body)] }));
+    const helperId = `${generatedId}-helper`;
+    const labelId = `${generatedId}-label`;
+    return (jsxs("div", { className: cn(theme.wrapperStyle, wrapperClassName), children: [label && (jsx(FormLabel, { id: labelId, htmlFor: generatedId, state: isDisabled ? "disabled" : isInvalid ? "invalid" : "default", required: required, className: "mb-1.5", children: label })), jsx("div", { ref: wrapperRef, className: cn(theme.inputGroupStyle, isInvalid && theme.invalidStyle, isFocused &&
+                    (isInvalid ? theme.invalidFocusStyle : theme.inputGroupFocusStyle)), children: createElement("div", { ...props, key: editorKey, ref: setEditableRef, id: generatedId, contentEditable: !isDisabled, suppressContentEditableWarning: true, onInput: handleInput, onKeyDown: handleKeyDown, onClick: handleClick, onFocus: handleFocus, onBlur: handleBlur, onPaste: handlePaste, onSelect: handleSelect, onCompositionStart: handleCompositionStart, onCompositionEnd: handleCompositionEnd, role: "combobox", "aria-autocomplete": "list", "aria-expanded": isDropdownOpen, "aria-haspopup": "listbox", "aria-controls": listboxId, "aria-placeholder": placeholder, "aria-required": required || undefined, "data-placeholder": placeholder, "aria-disabled": isDisabled || undefined, "aria-invalid": isInvalid || undefined, "aria-describedby": helperText ? helperId : undefined, "aria-labelledby": label ? labelId : undefined, className: cn(theme.editableStyle, theme.sizes[size], isContentEmpty &&
+                        "before:content-[attr(data-placeholder)] before:text-[var(--color-text-placeholder)] before:pointer-events-none before:absolute", isDisabled && "cursor-not-allowed opacity-60", className), style: {
+                        minHeight: rows ? `${rows * 1.5}em` : undefined,
+                        ...styleProp,
+                        position: "relative",
+                    } }, renderedSegments) }), helperText && (jsx("div", { id: helperId, className: cn("text-sm mt-1", isInvalid
+                    ? "text-[var(--color-danger)]"
+                    : "text-[var(--color-text-muted)]"), children: helperText })), isClient && createPortal(dropdownContent, document.body)] }));
 });
 Mention.displayName = "Mention";