@flikk/ui 1.0.0-beta.26 → 1.0.0-beta.29

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

@@ -1,11 +1,12 @@
+import React__default, { useMemo, useId, useState, useRef, useEffect, useCallback, useLayoutEffect, createElement } from 'react';
 import { jsx, jsxs } from 'react/jsx-runtime';
-import React__default, { useMemo, useId, useState, useRef, useEffect, useCallback, 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 { normalizeSegments, setCaretAtOffset, getPlainTextOffset, parseDOMToSegments, serializeSegments, serializeSegmentsMasked, insertMentionIntoSegments, MENTION_ATTR } from './Mention.utils.js';
@@ -74,7 +75,7 @@ const dropdownVariants = {
 // ---------------------------------------------------------------------------
 // Mention component
 // ---------------------------------------------------------------------------
-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, rows = 3, ...props }, ref) => {
+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, ...props }, ref) => {
     const theme = useMemo(() => ({ ...mentionTheme, ...(themeOverrides || {}) }), [themeOverrides]);
     const generatedId = useId();
     const isDisabled = state === "disabled" || disabled;
@@ -125,6 +126,25 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
     const dropdownRef = useRef(null);
     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();
@@ -244,10 +264,22 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
             }
         }
         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)
@@ -260,14 +292,18 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
         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;
-        if (!isControlled) {
-            onChange === null || onChange === void 0 ? void 0 : onChange(serialized);
-        }
-        else {
-            onChange === null || onChange === void 0 ? void 0 : onChange(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) {
@@ -275,7 +311,7 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
             const mention = detectActiveMention(maskedText, offset, triggerChars);
             setActiveMention(mention);
         }
-    }, [isControlled, onChange, triggerChars, notifyMentionsChange]);
+    }, [onChange, triggerChars, notifyMentionsChange, remountEditor]);
     const handleInput = useCallback(() => {
         setSelectedMentionIndex(null);
         updateFromDOM();
@@ -312,6 +348,7 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
         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);
@@ -321,9 +358,51 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
         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++;
+            }
+        }
+        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) => {
-        var _a, _b, _c, _d, _e;
+        var _a;
         // --- Selected mention: delete / replace / deselect ---
         if (selectedMentionIndex !== null &&
             ((_a = segments[selectedMentionIndex]) === null || _a === void 0 ? void 0 : _a.type) === "mention") {
@@ -338,6 +417,7 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
                 lastSerializedRef.current = serialized;
                 setSegments(newSegs);
                 setSelectedMentionIndex(null);
+                remountEditor();
                 onChange === null || onChange === void 0 ? void 0 : onChange(serialized);
                 notifyMentionsChange(newSegs);
                 return;
@@ -356,6 +436,7 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
                 lastSerializedRef.current = serialized;
                 setSegments(newSegs);
                 setSelectedMentionIndex(null);
+                remountEditor();
                 onChange === null || onChange === void 0 ? void 0 : onChange(serialized);
                 notifyMentionsChange(newSegs);
                 return;
@@ -408,10 +489,12 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
                 if (prevSibling &&
                     prevSibling.nodeType === Node.ELEMENT_NODE &&
                     prevSibling.hasAttribute(MENTION_ATTR)) {
-                    e.preventDefault();
-                    (_b = prevSibling.parentNode) === null || _b === void 0 ? void 0 : _b.removeChild(prevSibling);
-                    updateFromDOM();
-                    return;
+                    const segIdx = segmentIndexForMentionEl(prevSibling);
+                    if (segIdx !== -1) {
+                        e.preventDefault();
+                        removeMentionSegment(segIdx);
+                        return;
+                    }
                 }
             }
             // Case 2: Caret in parent element, child before offset is a mention
@@ -422,10 +505,12 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
                 if (prevChild &&
                     prevChild.nodeType === Node.ELEMENT_NODE &&
                     prevChild.hasAttribute(MENTION_ATTR)) {
-                    e.preventDefault();
-                    (_c = prevChild.parentNode) === null || _c === void 0 ? void 0 : _c.removeChild(prevChild);
-                    updateFromDOM();
-                    return;
+                    const segIdx = segmentIndexForMentionEl(prevChild);
+                    if (segIdx !== -1) {
+                        e.preventDefault();
+                        removeMentionSegment(segIdx);
+                        return;
+                    }
                 }
             }
         }
@@ -445,10 +530,12 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
                     if (nextSibling &&
                         nextSibling.nodeType === Node.ELEMENT_NODE &&
                         nextSibling.hasAttribute(MENTION_ATTR)) {
-                        e.preventDefault();
-                        (_d = nextSibling.parentNode) === null || _d === void 0 ? void 0 : _d.removeChild(nextSibling);
-                        updateFromDOM();
-                        return;
+                        const segIdx = segmentIndexForMentionEl(nextSibling);
+                        if (segIdx !== -1) {
+                            e.preventDefault();
+                            removeMentionSegment(segIdx);
+                            return;
+                        }
                     }
                 }
             }
@@ -458,10 +545,12 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
                 if (nextChild &&
                     nextChild.nodeType === Node.ELEMENT_NODE &&
                     nextChild.hasAttribute(MENTION_ATTR)) {
-                    e.preventDefault();
-                    (_e = nextChild.parentNode) === null || _e === void 0 ? void 0 : _e.removeChild(nextChild);
-                    updateFromDOM();
-                    return;
+                    const segIdx = segmentIndexForMentionEl(nextChild);
+                    if (segIdx !== -1) {
+                        e.preventDefault();
+                        removeMentionSegment(segIdx);
+                        return;
+                    }
                 }
             }
         }
@@ -475,7 +564,9 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
         highlightedIndex,
         filteredSuggestions,
         insertMention,
-        updateFromDOM,
+        segmentIndexForMentionEl,
+        removeMentionSegment,
+        remountEditor,
         selectedMentionIndex,
         segments,
         onChange,
@@ -513,26 +604,9 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
             setSelectedMentionIndex(null);
             return;
         }
-        // Find which DOM mention this is (nth occurrence)
-        const allMentions = editableRef.current.querySelectorAll(`[${MENTION_ATTR}]`);
-        const domIdx = Array.from(allMentions).indexOf(mentionEl);
-        if (domIdx === -1) {
-            setSelectedMentionIndex(null);
-            return;
-        }
-        // Map nth DOM mention → segment index
-        let count = 0;
-        for (let i = 0; i < segments.length; i++) {
-            if (segments[i].type === "mention") {
-                if (count === domIdx) {
-                    setSelectedMentionIndex(i);
-                    return;
-                }
-                count++;
-            }
-        }
-        setSelectedMentionIndex(null);
-    }, [segments]);
+        const segIdx = segmentIndexForMentionEl(mentionEl);
+        setSelectedMentionIndex(segIdx === -1 ? null : segIdx);
+    }, [segmentIndexForMentionEl]);
     // Scroll highlighted suggestion into view
     useEffect(() => {
         if (highlightedIndex >= 0 && dropdownRef.current) {
@@ -552,11 +626,22 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
     const renderedSegments = useMemo(() => {
         return segments.map((seg, i) => {
             if (seg.type === "text") {
-                return (jsx("span", { "data-segment": "text", children: seg.text || (i === 0 ? "" : "") }, `text-${i}`));
+                return (jsx("span", { "data-segment": "text", children: seg.text }, `text-${i}`));
             }
-            return (jsx(Tag, { size: mentionTagSize, removable: false, avatar: seg.data.avatar
-                    ? { src: seg.data.avatar, name: seg.data.label }
-                    : undefined, contentEditable: false, className: cn(theme.mentionTagStyle, i === selectedMentionIndex &&
+            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}`));
@@ -565,7 +650,8 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
         segments,
         mentionTagSize,
         mentionTagClassName,
-        theme.mentionTagStyle,
+        mentionTagRemovable,
+        removeMentionSegment,
         selectedMentionIndex,
     ]);
     // -----------------------------------------------------------------------
@@ -580,10 +666,17 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
                     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) => {
+        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: [jsx(Avatar, { src: suggestion.avatar, name: suggestion.label, size: "xs", className: "ring-0 border-0" }), 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
@@ -601,11 +694,13 @@ const Mention = React__default.forwardRef(({ triggers: triggersProp, suggestions
     // Render
     // -----------------------------------------------------------------------
     const helperId = `${generatedId}-helper`;
-    return (jsxs("div", { className: cn(theme.wrapperStyle, wrapperClassName), children: [label && (jsx(FormLabel, { htmlFor: generatedId, state: isDisabled ? "disabled" : isInvalid ? "invalid" : "default", required: required, className: "mb-1.5", children: label })), jsx("div", { ref: wrapperRef, className: cn(theme.inputGroupStyle, isFocused && theme.inputGroupFocusStyle, isInvalid && "border-[var(--color-danger)] ring-1 ring-[var(--color-danger)]"), children: jsx("div", { 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: "textbox", "aria-multiline": "true", "aria-autocomplete": "list", "aria-expanded": isDropdownOpen, "aria-haspopup": "listbox", "aria-placeholder": placeholder, "aria-required": required || undefined, "data-placeholder": placeholder, "aria-disabled": isDisabled || undefined, "aria-invalid": isInvalid || undefined, "aria-describedby": helperText ? helperId : 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 dark:before:text-[var(--color-neutral-500)]", isDisabled && "cursor-not-allowed opacity-60", className), style: {
+    return (jsxs("div", { className: cn(theme.wrapperStyle, wrapperClassName), children: [label && (jsx(FormLabel, { 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: "textbox", "aria-multiline": "true", "aria-autocomplete": "list", "aria-expanded": isDropdownOpen, "aria-haspopup": "listbox", "aria-placeholder": placeholder, "aria-required": required || undefined, "data-placeholder": placeholder, "aria-disabled": isDisabled || undefined, "aria-invalid": isInvalid || undefined, "aria-describedby": helperText ? helperId : 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",
-                    }, ...props, children: renderedSegments }) }), helperText && (jsx("div", { id: helperId, className: cn("text-sm mt-1", isInvalid
+                    } }, 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)] }));
 });

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

@@ -10,9 +10,11 @@ const mentionTheme = {
     // Input group container with outline and focus ring
     inputGroupStyle: formsBaseTheme.inputGroupBaseStyle,
     // JS-driven focus ring (applied when editable div is focused)
-    inputGroupFocusStyle: "shadow-[inset_0_0_0_2px_var(--color-primary-600)] " +
-        "ring-4 ring-[var(--color-primary)]/10 " +
-        "dark:shadow-[inset_0_0_0_2px_var(--color-primary-500)] dark:ring-[var(--color-primary-500)]/20",
+    inputGroupFocusStyle: formsBaseTheme.focusStates.default,
+    // Invalid state — inset box-shadow + danger fill (NOT border/ring; see CLAUDE.md §9)
+    invalidStyle: formsBaseTheme.states.invalid,
+    // Invalid + focused — danger inset shadow + danger ring glow
+    invalidFocusStyle: formsBaseTheme.focusStates.invalid,
     // Base editable div styles
     editableStyle: `${formsBaseTheme.controlBaseStyle} whitespace-pre-wrap break-words overflow-y-auto cursor-text`,
     // Size variants
@@ -21,35 +23,26 @@ const mentionTheme = {
         md: `${formsBaseTheme.sizes.md.text} ${formsBaseTheme.sizes.md.padding} ${formsBaseTheme.sizes.md.textareaHeight}`,
         lg: `${formsBaseTheme.sizes.lg.text} ${formsBaseTheme.sizes.lg.padding} ${formsBaseTheme.sizes.lg.textareaHeight}`,
     },
-    // Inline mention Tag chip styles
-    mentionTagStyle: "mx-0.5 align-baseline cursor-default select-none",
+    // Inline mention Tag chip styles.
     // Dropdown container - reuses the shared dropdown styles
-    dropdownStyle: formsBaseTheme.dropdownStyles.container + " py-1",
-    // Individual suggestion item
+    // p-1 (not py-1) so MenuItem rows' rounded highlight insets evenly on all
+    // sides instead of running flush to the container's left/right edges.
+    dropdownStyle: formsBaseTheme.dropdownStyles.container + " p-1",
+    // Suggestion rows render via the shared MenuItem primitive (avatar →
+    // startContent, label → children, description → subtitle). These two styles
+    // are only used by the custom `renderSuggestion` escape hatch, which wraps
+    // the consumer's node in a plain row that still tracks hover/highlight.
     suggestionStyle: "relative flex items-center gap-2.5 cursor-pointer select-none py-2 px-3 " +
         "text-[var(--color-text-primary)] " +
         "hover:text-[var(--color-primary)] hover:bg-[var(--color-primary-50)]/50 " +
         "dark:hover:text-[var(--color-primary-400)] dark:hover:bg-[var(--color-primary-400)]/10",
-    // Highlighted suggestion (keyboard navigation)
+    // Highlighted suggestion (keyboard navigation) — custom renderSuggestion path
     suggestionHighlightedStyle: "text-[var(--color-primary)] bg-[var(--color-primary-50)]/50 " +
         "dark:text-[var(--color-primary-400)] dark:bg-[var(--color-primary-400)]/10",
-    // Avatar image
-    suggestionAvatarStyle: "size-7 rounded-full object-cover shrink-0 " +
-        "bg-[var(--color-surface-sunken)] dark:bg-[var(--color-neutral-700)]",
-    // Avatar fallback (initials circle)
-    suggestionAvatarFallbackStyle: "size-7 rounded-full shrink-0 flex items-center justify-center text-xs font-medium " +
-        "bg-[var(--color-primary-100)] text-[var(--color-primary-700)] " +
-        "dark:bg-[var(--color-primary-900)] dark:text-[var(--color-primary-300)]",
-    // Suggestion label text
-    suggestionLabelStyle: "text-sm font-medium truncate",
-    // Suggestion description text
-    suggestionDescriptionStyle: "text-xs text-[var(--color-text-muted)] truncate " +
-        "dark:text-[var(--color-neutral-500)]",
     // Empty state
     emptyMessageStyle: formsBaseTheme.dropdownStyles.emptyMessage,
-    // Loading state
-    loadingStyle: "py-3 px-3 text-center text-[var(--color-text-muted)] " +
-        "dark:text-[var(--color-neutral-500)]",
+    // Loading state (--color-text-muted auto-flips for dark mode)
+    loadingStyle: "py-3 px-3 text-center text-[var(--color-text-muted)]",
 };
 
 export { mentionTheme };

package/dist/components/forms/Mention/Mention.types.d.ts

@@ -71,26 +71,21 @@ export interface MentionTheme {
     inputGroupStyle: string;
     /** JS-driven focus ring style */
     inputGroupFocusStyle: string;
+    /** Invalid state style (inset box-shadow + danger fill) */
+    invalidStyle: string;
+    /** Invalid + focused style (danger inset shadow + ring glow) */
+    invalidFocusStyle: string;
     /** Base editable div style */
     editableStyle: string;
     /** Size variants for the editable div */
     sizes: Record<MentionSize, string>;
-    /** Inline mention Tag chip style */
-    mentionTagStyle: string;
     /** Dropdown container style */
     dropdownStyle: string;
-    /** Individual suggestion item style */
+    /** Suggestion row style — used only by the custom `renderSuggestion` path
+     *  (default rows render via the shared MenuItem primitive). */
     suggestionStyle: string;
-    /** Highlighted (keyboard-focused) suggestion style */
+    /** Highlighted (keyboard-focused) suggestion style — custom renderSuggestion path */
     suggestionHighlightedStyle: string;
-    /** Avatar style inside a suggestion */
-    suggestionAvatarStyle: string;
-    /** Avatar fallback (initials) style */
-    suggestionAvatarFallbackStyle: string;
-    /** Suggestion label text style */
-    suggestionLabelStyle: string;
-    /** Suggestion description text style */
-    suggestionDescriptionStyle: string;
     /** Empty state message style */
     emptyMessageStyle: string;
     /** Loading state style */
@@ -153,6 +148,11 @@ export interface MentionProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
     mentionTagSize?: TagSize;
     /** Additional className for inline mention Tag chips */
     mentionTagClassName?: string;
+    /**
+     * Show a remove (×) button on each inline mention chip so it can be deleted
+     * by click as well as by keyboard. Defaults to `true`.
+     */
+    mentionTagRemovable?: boolean;
     /** Number of visible text rows (controls min-height) */
     rows?: number;
     /** Label rendered above the mention input */

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

@@ -1,5 +1,23 @@
 // Data attribute used to identify mention nodes in the DOM
 const MENTION_ATTR = "data-mention-id";
+/**
+ * True when `node` lives inside a mention chip (its avatar/label text nodes),
+ * as opposed to being the mention element itself. A TreeWalker descends into a
+ * FILTER_ACCEPTed mention element, so without rejecting these inner nodes the
+ * offset walkers would count a chip's inner text and land the caret inside it
+ * (chips are contentEditable=false). Stops at `container` (the walker root).
+ */
+const isInsideMention = (node, container) => {
+    let parent = node.parentNode;
+    while (parent && parent !== container) {
+        if (parent.nodeType === Node.ELEMENT_NODE &&
+            parent.hasAttribute(MENTION_ATTR)) {
+            return true;
+        }
+        parent = parent.parentNode;
+    }
+    return false;
+};
 /**
  * Serialize segments to a plain text string.
  * Mentions become `trigger + label` (e.g. "@Sarah Wilson").
@@ -111,12 +129,17 @@ const getPlainTextOffset = (container) => {
     let offset = 0;
     const walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT | NodeFilter.SHOW_ELEMENT, {
         acceptNode: (node) => {
-            if (node.nodeType === Node.TEXT_NODE)
-                return NodeFilter.FILTER_ACCEPT;
+            // Mention element: count it atomically (its inner nodes are rejected below)
             if (node.nodeType === Node.ELEMENT_NODE &&
                 node.hasAttribute(MENTION_ATTR)) {
                 return NodeFilter.FILTER_ACCEPT;
             }
+            // Reject the chip's inner avatar/label nodes so the walker never
+            // descends into a mention or counts its inner text twice.
+            if (isInsideMention(node, container))
+                return NodeFilter.FILTER_REJECT;
+            if (node.nodeType === Node.TEXT_NODE)
+                return NodeFilter.FILTER_ACCEPT;
             // Skip non-mention element nodes but traverse their children
             return NodeFilter.FILTER_SKIP;
         },
@@ -234,12 +257,17 @@ const setCaretAtOffset = (container, targetOffset) => {
     let remaining = targetOffset;
     const walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT | NodeFilter.SHOW_ELEMENT, {
         acceptNode: (node) => {
-            if (node.nodeType === Node.TEXT_NODE)
-                return NodeFilter.FILTER_ACCEPT;
+            // Mention element: count it atomically (its inner nodes are rejected below)
             if (node.nodeType === Node.ELEMENT_NODE &&
                 node.hasAttribute(MENTION_ATTR)) {
                 return NodeFilter.FILTER_ACCEPT;
             }
+            // Reject the chip's inner avatar/label nodes so the caret is never
+            // placed inside a mention (chips are contentEditable=false).
+            if (isInsideMention(node, container))
+                return NodeFilter.FILTER_REJECT;
+            if (node.nodeType === Node.TEXT_NODE)
+                return NodeFilter.FILTER_ACCEPT;
             return NodeFilter.FILTER_SKIP;
         },
     });

package/dist/components/forms/RichTextEditor/RichTextEditor.js

@@ -1437,11 +1437,11 @@ const RichTextEditor = React__default.forwardRef(({ size = "md", state = "defaul
                                                     : false;
         switch (tool) {
             case "bold":
-                return (jsx(Button, { size: "sm", color: "neutral", variant: "soft", iconOnly: true, className: cn(themeStyles.toolbarButtonStyle), "data-state": isActive ? "active" : "inactive", onMouseDown: handleMouseDown, onClick: handleBold, disabled: isDisabled, "aria-label": "Bold", "aria-pressed": isActive ? "true" : "false", children: jsx(BoldIcon, { className: "w-4 h-4" }) }, toolKey));
+                return (jsx(Button, { size: "sm", color: "neutral", variant: "soft", iconOnly: true, className: cn(themeStyles.toolbarButtonStyle), "data-state": isActive ? "active" : "inactive", onMouseDown: handleMouseDown, onClick: handleBold, disabled: isDisabled, "aria-label": "Bold", "aria-pressed": isActive ? "true" : "false", children: jsx(BoldIcon, { className: "size-4" }) }, toolKey));
             case "italic":
-                return (jsx(Button, { size: "sm", color: "neutral", variant: "soft", iconOnly: true, className: cn(themeStyles.toolbarButtonStyle), "data-state": isActive ? "active" : "inactive", onMouseDown: handleMouseDown, onClick: handleItalic, disabled: isDisabled, "aria-label": "Italic", "aria-pressed": isActive ? "true" : "false", children: jsx(ItalicIcon, { className: "w-4 h-4" }) }, toolKey));
+                return (jsx(Button, { size: "sm", color: "neutral", variant: "soft", iconOnly: true, className: cn(themeStyles.toolbarButtonStyle), "data-state": isActive ? "active" : "inactive", onMouseDown: handleMouseDown, onClick: handleItalic, disabled: isDisabled, "aria-label": "Italic", "aria-pressed": isActive ? "true" : "false", children: jsx(ItalicIcon, { className: "size-4" }) }, toolKey));
             case "underline":
-                return (jsx(Button, { size: "sm", color: "neutral", variant: "soft", iconOnly: true, className: cn(themeStyles.toolbarButtonStyle), "data-state": isActive ? "active" : "inactive", onMouseDown: handleMouseDown, onClick: handleUnderline, disabled: isDisabled, "aria-label": "Underline", "aria-pressed": isActive ? "true" : "false", children: jsx(UnderlineIcon, { className: "w-4 h-4" }) }, toolKey));
+                return (jsx(Button, { size: "sm", color: "neutral", variant: "soft", iconOnly: true, className: cn(themeStyles.toolbarButtonStyle), "data-state": isActive ? "active" : "inactive", onMouseDown: handleMouseDown, onClick: handleUnderline, disabled: isDisabled, "aria-label": "Underline", "aria-pressed": isActive ? "true" : "false", children: jsx(UnderlineIcon, { className: "size-4" }) }, toolKey));
             case "fontFamily": {
                 // The `fontFamily` tool is opt-in via toolbar config, but
                 // `fontFamilies` is also a public prop — if a consumer passes an

package/dist/components/forms/RichTextEditor/RichTextEditor.theme.js

@@ -97,16 +97,16 @@ const richTextEditorTheme = {
     // `rounded-t-[var(--form-radius)]` matches the container's radius so the
     // toolbar's own bg/backdrop-blur respects the top corners — prevents the
     // 1px bleed past the parent's `overflow-hidden` clip in Safari/Chromium.
-    toolbarStyle: "flex items-center gap-1 p-1 rounded-t-[var(--form-radius)] border-b border-[var(--color-border)] dark:bg-[var(--color-background-secondary)]",
+    toolbarStyle: "flex items-center m-0.5 gap-0.5 p-0.5 rounded-[var(--form-radius)] dark:bg-[var(--color-surface)]/0",
     // Toolbar styling (floating variant — selection-anchored)
-    floatingToolbarStyle: "flex items-center gap-1 p-1 rounded-xl border border-[var(--color-border)] bg-white/90 backdrop-blur-sm shadow-real-xl overflow-hidden dark:bg-[var(--color-background-secondary)]/80",
+    floatingToolbarStyle: "flex items-center gap-1 p-1 rounded-xl border border-[var(--color-border)] bg-[var(--color-surface-overlay)]/80 backdrop-blur-md shadow-real-xl overflow-hidden",
     // Toolbar button — single source of truth via data-[state=active]
     // (aria-pressed remains as proper ARIA on toggle buttons, but styling is decoupled)
-    toolbarButtonStyle: "inline-flex items-center justify-center size-8 rounded-[calc(var(--radius-base)*0.85)] border border-transparent bg-transparent text-[var(--color-text-secondary)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-background-secondary)] transition-colors duration-300 disabled:opacity-50 disabled:cursor-not-allowed data-[state=active]:bg-[var(--color-background-secondary)] data-[state=active]:text-[var(--color-text-primary)] data-[state=active]:border-[var(--color-border)] data-[state=active]:shadow-inner",
+    toolbarButtonStyle: "inline-flex items-center justify-center rounded-[calc(var(--radius-base)*0.85)] border border-transparent bg-transparent text-[var(--color-text-secondary)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-background-secondary)] transition-colors duration-300 disabled:opacity-50 disabled:cursor-not-allowed data-[state=active]:bg-[var(--color-background-secondary)] data-[state=active]:text-[var(--color-text-primary)] data-[state=active]:border-[var(--color-border)] data-[state=active]:shadow-inner",
     // Dropdown surface (visual only — positioning handled at use site via portal)
-    dropdownStyle: "min-w-[120px] max-h-[18rem] overflow-y-auto py-1 bg-white/90 backdrop-blur-md rounded-[var(--form-radius)] shadow-xl ring-1 ring-[var(--color-border)] focus:outline-none",
+    dropdownStyle: "min-w-[120px] max-h-[18rem] overflow-y-auto py-1 bg-[var(--color-surface-overlay)]/80 backdrop-blur-md rounded-[var(--form-radius)] shadow-xl ring-1 ring-[var(--color-border)] focus:outline-none",
     // Dropdown item — uses data-[active=true] for selected state
-    dropdownItemStyle: "block w-full px-3 py-2 text-left text-sm text-[var(--color-text-primary)] hover:bg-[var(--color-surface-hover)] transition-colors duration-150 disabled:opacity-50 disabled:cursor-not-allowed data-[active=true]:bg-[var(--color-primary-50)] data-[active=true]:text-[var(--color-primary-900)]",
+    dropdownItemStyle: "block w-full px-3 py-2 text-left text-sm text-[var(--color-text-primary)] hover:bg-[var(--color-surface-hover)] transition-colors duration-150 disabled:opacity-50 disabled:cursor-not-allowed data-[active=true]:bg-[var(--color-primary-50)] data-[active=true]:text-[var(--color-primary-900)] data-[active=true]:dark:bg-[var(--color-primary-400)]/10 data-[active=true]:dark:text-[var(--color-primary-400)]",
     // Separator between toolbar sections
     separatorStyle: "w-px h-6 bg-[var(--color-border)] mx-1",
     // Color picker layout — column of family rows, plus optional Recent + Mono rows

package/dist/components/forms/Select/Select.js

@@ -96,7 +96,7 @@ const SelectButton = ({ id, disabled, isOpen, state = "default", size = "md", ic
     // Use either the themed focus state or directly apply the focus classes if the theme is not working
     const activeFocusState = isOpen
         ? focusStateStyle ||
-            "shadow-[inset_0_0_0_2px_var(--color-primary)] ring-4 ring-[var(--color-primary)]/10"
+            "shadow-[inset_0_0_0_1px_var(--color-primary)] ring-4 ring-[var(--color-primary)]/10"
         : "";
     return (jsxs("div", { className: cn(buttonWrapperStyle, "flex items-stretch"), children: [contentStart && (jsx("div", { "data-slot": "content-start", className: cn(contentSlotStyle, "pr-0 border-r border-[var(--color-border)]"), children: contentStart })), jsxs("button", { ref: buttonRef, id: id, type: "button", className: cn(baseStyle, sizeStyle, stateStyle, hoverStateStyle, activeFocusState, iconStartPadding, iconEndPadding, buttonStyle, "flex-1 min-w-0", className), onClick: onClick, onFocus: onFocus, onBlur: onBlur, disabled: disabled, "aria-expanded": isOpen, "aria-haspopup": "listbox", "aria-controls": isOpen && id ? `${id}-listbox` : undefined, "aria-labelledby": ariaLabelledby, "aria-invalid": ariaInvalid, "aria-describedby": ariaDescribedby, children: [iconStart && jsx("span", { className: iconStartStyle, children: iconStart }), children, iconEnd && jsx("span", { className: iconEndStyle, children: iconEnd })] }), contentEnd && (jsx("div", { "data-slot": "content-end", className: cn(contentSlotStyle, "pl-0 border-l border-[var(--color-border)]"), children: contentEnd }))] }));
 };
@@ -287,7 +287,7 @@ const SelectOptions = ({ isOpen, maxHeight = "15rem", className = "", onClose, c
                         } }) })), children] })) }));
     // Use portal if enabled and client-side - wrap with dark class for dark mode support
     if (portal && isClient) {
-        return createPortal(jsx("div", { className: isDarkMode ? "dark" : undefined, children: optionsContent }), document.body);
+        return createPortal(jsx("div", { "data-flikkui-portal": "", className: isDarkMode ? "dark" : undefined, children: optionsContent }), document.body);
     }
     return optionsContent;
 };

package/dist/components/forms/Select/Select.theme.js

@@ -11,12 +11,12 @@ const selectTheme = {
     baseStyle: formsBaseTheme.inputGroupBaseStyle + " items-center justify-between",
     // Button wrapper style
     buttonWrapperStyle: "relative w-full",
-    // Button style - bg-white for light mode only; dark mode bg comes from baseStyle (inputGroupBaseStyle)
-    buttonStyle: "w-full cursor-pointer bg-white dark:bg-[var(--color-neutral-900)]",
+    // Button style - surface flips automatically between light/dark
+    buttonStyle: "w-full cursor-pointer bg-[var(--color-surface)]",
     // Placeholder text style - matches Input placeholder styling
     placeholderTextStyle: formsBaseTheme.placeholderStyle,
     // Selected value text style
-    valueTextStyle: "text-[var(--color-text-primary)] dark:text-[var(--color-neutral-200)]",
+    valueTextStyle: "text-[var(--color-text-primary)]",
     // Size variants - composed from atomic tokens
     sizes: {
         sm: `${formsBaseTheme.sizes.sm.text} ${formsBaseTheme.sizes.sm.padding} ${formsBaseTheme.sizes.sm.height}`,