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

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

@@ -1,36 +1,22 @@
-/**
- * Default theme for the FileUpload component
- * Uses production-ready CSS variables from global.scss
- */
 const fileUploadTheme = {
-    // Container wrapper
+    // Root container
     containerStyle: "w-full",
     // Dropzone area (default state)
-    dropzoneStyle: "relative flex flex-col items-center justify-center w-full min-h-[160px] p-6 border border-dashed border-[var(--color-border)] rounded-[var(--form-radius)] bg-[var(--color-background-secondary)] hover:bg-[var(--color-background-secondary)] hover:border-[var(--color-primary)] transition-colors duration-400 cursor-pointer",
-    // Dropzone when dragging over
-    dropzoneActiveStyle: "border-[var(--color-primary)] bg-[var(--color-primary-50)] scale-[1.01]",
-    // Dropzone when disabled
-    dropzoneDisabledStyle: "cursor-not-allowed opacity-60 hover:bg-[var(--color-background-secondary)] hover:border-[var(--color-border)]",
-    // Content wrapper inside dropzone
-    contentStyle: "flex flex-col items-center text-center pointer-events-none",
-    // Upload icon
-    iconStyle: "size-8 text-[var(--color-text-placeholder)]",
-    // Main text
-    textStyle: "text-sm font-medium text-[var(--color-text-primary)]",
-    // Helper text
-    helperTextStyle: "text-sm text-[var(--color-text-muted)] mt-1",
-    // Description below dropzone
-    descriptionStyle: "text-xs text-[var(--color-text-muted)] mt-1",
-    // Preview container
-    previewContainerStyle: "grid grid-cols-2 sm:grid-cols-3 md:grid-cols-4 gap-4 mt-4",
-    // Individual preview item
-    previewItemStyle: "relative group rounded-[var(--radius-base)] border border-[var(--color-border)] overflow-hidden bg-[var(--color-background-secondary)]",
-    // Preview image
-    previewImageStyle: "w-full h-32 object-cover",
-    // Preview file (non-image)
-    previewFileStyle: "flex items-center justify-center w-full h-32 p-3 text-sm text-[var(--color-text-secondary)] text-center break-all",
-    // Remove button
-    removeButtonStyle: "absolute top-1 right-1  -translate-y-1 opacity-0 group-hover:opacity-100 transition-all duration-400 group-hover:-translate-y-0",
+    dropzoneStyle: "relative flex flex-col items-center justify-center w-full min-h-[160px] p-6 border border-dashed border-[var(--color-border)] rounded-[var(--form-radius)] bg-[var(--color-surface)] hover:border-[var(--color-border-hover)] transition-colors duration-400 cursor-pointer",
+    // Dragging over — translucent primary tint composites over the surface in both modes
+    dropzoneActiveStyle: "border-solid border-[var(--color-primary)] bg-[var(--color-primary)]/5",
+    // Disabled
+    dropzoneDisabledStyle: "cursor-not-allowed opacity-60 hover:bg-[var(--color-surface)] hover:border-[var(--color-border)]",
+    // Wrapping row of fixed-width thumbnails (not a stretch grid)
+    previewContainerStyle: "flex flex-wrap gap-1 mt-2",
+    // Fixed responsive thumbnail — stays small on large containers, wraps to more-per-row
+    previewItemStyle: "relative group shrink-0 size-10 sm:size-12 md:size-16 rounded-[var(--radius-base)] border border-[var(--color-border)] overflow-hidden bg-[var(--color-surface)]",
+    // Image fills the thumbnail box
+    previewImageStyle: "size-full object-cover",
+    // Non-image tile — centered document icon (filename surfaced via title tooltip)
+    previewFileStyle: "flex items-center justify-center size-full text-[var(--color-text-muted)]",
+    // Remove button (revealed on item hover)
+    removeButtonStyle: "absolute top-1 right-1 -translate-y-1 opacity-0 group-hover:opacity-100 transition-all duration-400 group-hover:-translate-y-0",
 };
 
 export { fileUploadTheme };

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

@@ -4,7 +4,7 @@ export type FileUploadState = "default" | "disabled" | "invalid";
  * FileUpload component props
  * Supports both click-to-upload and drag-and-drop
  */
-export interface FileUploadProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onError'> {
+export interface FileUploadProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onError' | 'onChange'> {
     /**
      * Accepted file types (MIME types or file extensions)
      * @example ["image/*", ".pdf", ".doc"]
@@ -43,7 +43,22 @@ export interface FileUploadProps extends Omit<React.HTMLAttributes<HTMLDivElemen
      */
     errorMessage?: React.ReactNode;
     /**
-     * Callback when files are selected/dropped
+     * Controlled file list. When provided, the component is controlled and the
+     * parent owns the list — pair with `onChange`. Leave undefined for the
+     * uncontrolled behavior (the component tracks its own list internally).
+     */
+    value?: File[];
+    /**
+     * Initial file list for the uncontrolled case. Ignored when `value` is set.
+     */
+    defaultFiles?: File[];
+    /**
+     * Callback fired whenever the full file list changes (add or remove),
+     * with the complete next list. Required to read state in controlled mode.
+     */
+    onChange?: (files: File[]) => void;
+    /**
+     * Callback when files are selected/dropped, with only the newly added files.
      */
     onUpload?: (files: File[]) => void;
     /**
@@ -59,20 +74,26 @@ export interface FileUploadProps extends Omit<React.HTMLAttributes<HTMLDivElemen
      * @default true
      */
     showPreview?: boolean;
+    /**
+     * Show the upload icon inside the dropzone. Set `false` for slim/compact
+     * containers where the icon would crowd the text.
+     * @default true
+     */
+    showIcon?: boolean;
     /**
      * Custom upload button text
      * @default "Choose files"
      */
-    buttonText?: string;
+    buttonText?: React.ReactNode;
     /**
      * Custom dropzone helper text
      * @default "or drag and drop"
      */
-    helperText?: string;
+    helperText?: React.ReactNode;
     /**
      * Helper text displayed below the upload area
      */
-    description?: string;
+    description?: React.ReactNode;
     /**
      * Custom CSS class for the container
      */
@@ -96,11 +117,6 @@ export interface FileUploadThemeOverrides {
     dropzoneStyle?: string;
     dropzoneActiveStyle?: string;
     dropzoneDisabledStyle?: string;
-    contentStyle?: string;
-    iconStyle?: string;
-    textStyle?: string;
-    helperTextStyle?: string;
-    descriptionStyle?: string;
     previewContainerStyle?: string;
     previewItemStyle?: string;
     previewImageStyle?: string;

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

@@ -9,14 +9,16 @@ const inputTheme = {
     wrapperStyle: formsBaseTheme.wrapperStyle,
     // Input group styles - no focus-within (focus is managed via JS for contentStart/contentEnd compatibility)
     inputGroupStyle: "relative flex rounded-[var(--form-radius)] shadow-[inset_0_0_0_1px_var(--color-border)] " +
-        "bg-white transition-all " +
-        "dark:shadow-[inset_0_0_0_1px_var(--color-neutral-700)] dark:bg-[var(--color-neutral-900)]",
+        "bg-[var(--color-surface)] transition-all " +
+        // Hover edge: strengthen the border to --color-border-secondary on hover. Scoped with
+        // not-focus-within so the JS-driven focus border (primary) always wins.
+        "not-focus-within:hover:shadow-[inset_0_0_0_1px_var(--color-border-secondary)]",
     // JS-driven focus ring (applied when isFocused is true)
-    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: "shadow-[inset_0_0_0_1px_var(--color-primary-600)] ring-4 ring-[var(--color-primary)]/10 " +
+        "dark:shadow-[inset_0_0_0_1px_var(--color-primary-500)] dark:ring-[var(--color-primary-500)]/20",
     // JS-driven focus ring for invalid state
-    inputGroupFocusInvalidStyle: "shadow-[inset_0_0_0_2px_var(--color-danger)] ring-4 ring-[var(--color-danger)]/10 " +
-        "dark:shadow-[inset_0_0_0_2px_var(--color-danger-500)] dark:ring-[var(--color-danger-500)]/20",
+    inputGroupFocusInvalidStyle: "shadow-[inset_0_0_0_1px_var(--color-danger)] ring-4 ring-[var(--color-danger)]/10 " +
+        "dark:shadow-[inset_0_0_0_1px_var(--color-danger-500)] dark:ring-[var(--color-danger-500)]/20",
     // Base input styles - extends common form control with design tokens
     baseStyle: `${formsBaseTheme.controlBaseStyle} py-2 px-3`,
     // Size variants - composed from atomic tokens
@@ -30,7 +32,10 @@ const inputTheme = {
         default: formsBaseTheme.states.default,
         disabled: formsBaseTheme.states.disabled,
         invalid: "shadow-[inset_0_0_0_1px_var(--color-danger)] bg-[var(--color-danger-50)] " +
-            "dark:bg-[var(--color-danger-950)]/30 dark:shadow-[inset_0_0_0_1px_var(--color-danger-500)]",
+            // Keep the danger border on hover (don't let the hover edge override it)
+            "not-focus-within:hover:shadow-[inset_0_0_0_1px_var(--color-danger)] " +
+            "dark:bg-[var(--color-danger-950)]/30 dark:shadow-[inset_0_0_0_1px_var(--color-danger-500)] " +
+            "dark:not-focus-within:hover:shadow-[inset_0_0_0_1px_var(--color-danger-500)]",
     },
     // Helper text styles with state handling
     helperText: formsBaseTheme.helperText,
@@ -66,9 +71,7 @@ const inputTheme = {
     numberButtonsContainerStyle: "absolute inset-y-0 right-0 flex flex-row items-center pr-2 z-10 gap-1",
     numberButtonStyle: "bg-[var(--color-background-secondary)] flex items-center justify-center " +
         "text-[var(--color-text-muted)] hover:bg-[var(--color-surface-hover)] " +
-        "hover:text-[var(--color-text-primary)] cursor-pointer size-6 rounded-sm transition-colors " +
-        "dark:bg-[var(--color-neutral-800)] dark:text-[var(--color-neutral-500)] " +
-        "dark:hover:bg-[var(--color-neutral-700)] dark:hover:text-[var(--color-neutral-200)]",
+        "hover:text-[var(--color-text-primary)] cursor-pointer size-6 rounded-sm transition-colors",
     // Type-specific styles organized by input type
     typeStyles: {
         password: {

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

@@ -3,7 +3,7 @@
  * Follows Flikkui design system with CSS variables
  */
 const inputCounterTheme = {
-    baseStyle: "flex items-center gap-3 transition-all p-1 border border-[var(--color-border)] rounded-[var(--form-radius)] w-fit",
+    baseStyle: "flex items-center gap-3 transition-all p-1 bg-[var(--color-surface)] border border-[var(--color-border)] rounded-[var(--form-radius)] w-fit",
     buttonWrapperStyle: "flex-shrink-0",
     numberStyle: "min-w-fit text-center text-sm font-medium text-[var(--color-text-primary)] tabular-nums select-none",
 };

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 };