@flikk/ui 1.0.0-beta.2 → 1.0.0-beta.4

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

@@ -0,0 +1,410 @@
+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 { useIsClient } from '../../../hooks/useIsClient.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 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);
+    const lower = query.toLowerCase();
+    return suggestions
+        .filter((s) => s.label.toLowerCase().includes(lower) ||
+        (s.description && s.description.toLowerCase().includes(lower)))
+        .slice(0, max);
+};
+// ---------------------------------------------------------------------------
+// Dropdown animation
+// ---------------------------------------------------------------------------
+const dropdownVariants = {
+    initial: { opacity: 0, y: -6, scale: 0.96 },
+    visible: {
+        opacity: 1,
+        y: 0,
+        scale: 1,
+        transition: { duration: 0.18, ease: "easeOut" },
+    },
+    exit: {
+        opacity: 0,
+        y: -6,
+        scale: 0.96,
+        transition: { duration: 0.12, ease: "easeIn" },
+    },
+};
+// ---------------------------------------------------------------------------
+// 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 theme = useMemo(() => ({ ...mentionTheme, ...(themeOverrides || {}) }), [themeOverrides]);
+    // Normalize triggers from both APIs
+    const triggers = useMemo(() => {
+        if (triggersProp && triggersProp.length > 0)
+            return triggersProp;
+        // Simple API: wrap suggestions + onSearch into a single '@' trigger
+        return [
+            {
+                trigger: "@",
+                suggestions: suggestionsProp || [],
+                onSearch: onSearchProp,
+            },
+        ];
+    }, [triggersProp, suggestionsProp, onSearchProp]);
+    const triggerChars = useMemo(() => triggers.map((t) => t.trigger), [triggers]);
+    // Value state (controlled / uncontrolled)
+    const [internalValue, setInternalValue] = useState(defaultValue);
+    const isControlled = controlledValue !== undefined;
+    const textValue = isControlled ? controlledValue : internalValue;
+    // Focus state for input group styling
+    const [isFocused, setIsFocused] = useState(false);
+    // Active mention context
+    const [activeMention, setActiveMention] = useState(null);
+    const [highlightedIndex, setHighlightedIndex] = useState(-1);
+    // Dropdown position
+    const [dropdownPos, setDropdownPos] = useState({
+        top: -9999,
+        left: -9999,
+        width: 280,
+    });
+    // Refs
+    const textareaRef = useRef(null);
+    const wrapperRef = useRef(null);
+    const dropdownRef = useRef(null);
+    // SSR guard for portal
+    const isClient = useIsClient();
+    // Combine forwarded ref with internal ref
+    const setTextareaRef = useCallback((el) => {
+        textareaRef.current = el;
+        if (typeof ref === "function") {
+            ref(el);
+        }
+        else if (ref) {
+            ref.current =
+                el;
+        }
+    }, [ref]);
+    // Get the current trigger config for the active mention
+    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 [];
+        return filterSuggestions(activeTriggerConfig.suggestions, (activeMention === null || activeMention === void 0 ? void 0 : activeMention.query) || "", maxSuggestions);
+    }, [activeTriggerConfig, activeMention === null || activeMention === void 0 ? void 0 : activeMention.query, maxSuggestions]);
+    const isDropdownOpen = activeMention !== null && (filteredSuggestions.length > 0 || loading);
+    // Fire onSearch when query changes
+    useEffect(() => {
+        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
+    // 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,
+        };
+    }, []);
+    const updateDropdownPosition = useCallback(() => {
+        const pos = measureCaretPosition();
+        if (!pos)
+            return;
+        const lineHeight = parseFloat(window.getComputedStyle(textareaRef.current).lineHeight || "20");
+        setDropdownPos({
+            top: pos.top + lineHeight + 4,
+            left: pos.left,
+            width: 280,
+        });
+    }, [measureCaretPosition]);
+    // Reposition dropdown whenever the active mention changes
+    useLayoutEffect(() => {
+        if (activeMention) {
+            updateDropdownPosition();
+        }
+    }, [activeMention, updateDropdownPosition]);
+    // Reposition on scroll / resize
+    useEffect(() => {
+        if (!isDropdownOpen)
+            return;
+        const handleReposition = () => updateDropdownPosition();
+        window.addEventListener("scroll", handleReposition, {
+            passive: true,
+            capture: true,
+        });
+        window.addEventListener("resize", handleReposition, { passive: true });
+        return () => {
+            window.removeEventListener("scroll", handleReposition, true);
+            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)) {
+                setActiveMention(null);
+            }
+        };
+        document.addEventListener("mousedown", handleClickOutside);
+        return () => document.removeEventListener("mousedown", handleClickOutside);
+    }, [isDropdownOpen]);
+    // -----------------------------------------------------------------------
+    // Handlers
+    // -----------------------------------------------------------------------
+    const setValue = useCallback((newValue) => {
+        if (!isControlled) {
+            setInternalValue(newValue);
+        }
+        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]);
+    const insertMention = useCallback((suggestion) => {
+        if (!activeMention || !textareaRef.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);
+        setActiveMention(null);
+        setHighlightedIndex(-1);
+        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, textValue, setValue, onMentionSelect]);
+    const handleKeyDown = useCallback((e) => {
+        if (!isDropdownOpen)
+            return;
+        switch (e.key) {
+            case "ArrowDown":
+                e.preventDefault();
+                setHighlightedIndex((prev) => prev >= filteredSuggestions.length - 1 ? 0 : prev + 1);
+                break;
+            case "ArrowUp":
+                e.preventDefault();
+                setHighlightedIndex((prev) => prev <= 0 ? filteredSuggestions.length - 1 : prev - 1);
+                break;
+            case "Enter":
+                if (highlightedIndex >= 0 && highlightedIndex < filteredSuggestions.length) {
+                    e.preventDefault();
+                    insertMention(filteredSuggestions[highlightedIndex]);
+                }
+                break;
+            case "Escape":
+                e.preventDefault();
+                setActiveMention(null);
+                break;
+            case "Tab":
+                // Close dropdown on tab without preventing default
+                setActiveMention(null);
+                break;
+        }
+    }, [isDropdownOpen, highlightedIndex, filteredSuggestions, insertMention]);
+    const handleFocus = useCallback((e) => {
+        var _a;
+        setIsFocused(true);
+        (_a = props.onFocus) === null || _a === void 0 ? void 0 : _a.call(props, e);
+    }, [props.onFocus]);
+    const handleBlur = useCallback((e) => {
+        var _a;
+        setIsFocused(false);
+        (_a = props.onBlur) === null || _a === void 0 ? void 0 : _a.call(props, e);
+    }, [props.onBlur]);
+    // Scroll highlighted suggestion into view
+    useEffect(() => {
+        if (highlightedIndex >= 0 && dropdownRef.current) {
+            const item = dropdownRef.current.querySelector(`[data-suggestion-index="${highlightedIndex}"]`);
+            if (item) {
+                item.scrollIntoView({ block: "nearest" });
+            }
+        }
+    }, [highlightedIndex]);
+    // -----------------------------------------------------------------------
+    // 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
+                    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
+                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));
+    };
+    // -----------------------------------------------------------------------
+    // 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: {
+                position: "fixed",
+                top: `${dropdownPos.top}px`,
+                left: `${dropdownPos.left}px`,
+                minWidth: `${dropdownPos.width}px`,
+                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))) })) }));
+    // -----------------------------------------------------------------------
+    // 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)] }));
+});
+Mention.displayName = "Mention";
+
+export { Mention };

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

@@ -0,0 +1,6 @@
+import type { MentionTheme } from "./Mention.types";
+/**
+ * Default theme for the Mention component.
+ * Uses the shared forms base theme for consistency with Input/Textarea.
+ */
+export declare const mentionTheme: MentionTheme;

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

@@ -0,0 +1,56 @@
+import { formsBaseTheme } from '../forms.theme.js';
+
+/**
+ * Default theme for the Mention component.
+ * Uses the shared forms base theme for consistency with Input/Textarea.
+ */
+const mentionTheme = {
+    // Outermost wrapper
+    wrapperStyle: formsBaseTheme.wrapperStyle,
+    // Input group container with outline and focus ring
+    inputGroupStyle: formsBaseTheme.inputGroupBaseStyle,
+    // JS-driven focus ring (applied when textarea is focused)
+    inputGroupFocusStyle: "outline-2 outline-[var(--color-primary-600)] -outline-offset-1 " +
+        "ring-4 ring-[var(--color-primary)]/10 " +
+        "dark:outline-[var(--color-primary-500)] dark:ring-[var(--color-primary-500)]/20",
+    // Base textarea styles
+    textareaStyle: `${formsBaseTheme.controlBaseStyle} resize-y`,
+    // Size variants
+    sizes: {
+        sm: `${formsBaseTheme.sizes.sm.text} ${formsBaseTheme.sizes.sm.padding} ${formsBaseTheme.sizes.sm.textareaHeight}`,
+        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}`,
+    },
+    // Dropdown container - reuses the shared dropdown styles
+    dropdownStyle: formsBaseTheme.dropdownStyles.container + " py-1",
+    // Individual suggestion item
+    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)
+    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-background-tertiary)] 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)]",
+    // Highlighted mention text in the overlay
+    mentionHighlightStyle: "text-[var(--color-primary)] font-medium " +
+        "dark:text-[var(--color-primary-400)]",
+};
+
+export { mentionTheme };

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

@@ -0,0 +1,111 @@
+import React from "react";
+/**
+ * A single suggestion item displayed in the mention dropdown.
+ */
+export interface MentionSuggestion {
+    /** Unique identifier for the suggestion */
+    id: string;
+    /** Display label (e.g. user name, tag name) */
+    label: string;
+    /** Optional avatar URL */
+    avatar?: string;
+    /** Optional description line (e.g. job title, email) */
+    description?: string;
+    /** Allow arbitrary metadata */
+    [key: string]: unknown;
+}
+/**
+ * Configuration for a single trigger character and its suggestions.
+ */
+export interface MentionTrigger {
+    /** The trigger character (e.g. '@', '#') */
+    trigger: string;
+    /** Available suggestions for this trigger */
+    suggestions: MentionSuggestion[];
+    /** Async search callback invoked when the user types after the trigger */
+    onSearch?: (query: string) => void | Promise<void>;
+}
+/**
+ * Size variants for the Mention component.
+ */
+export type MentionSize = "sm" | "md" | "lg";
+/**
+ * Theme configuration for the Mention component.
+ */
+export interface MentionTheme {
+    /** Outermost wrapper style */
+    wrapperStyle: string;
+    /** Input group container style (border, focus ring) */
+    inputGroupStyle: string;
+    /** JS-driven focus ring style */
+    inputGroupFocusStyle: string;
+    /** Base textarea style */
+    textareaStyle: string;
+    /** Size variants for the textarea */
+    sizes: Record<MentionSize, string>;
+    /** Dropdown container style */
+    dropdownStyle: string;
+    /** Individual suggestion item style */
+    suggestionStyle: string;
+    /** Highlighted (keyboard-focused) suggestion style */
+    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 */
+    loadingStyle: string;
+    /** Highlighted mention text overlay style */
+    mentionHighlightStyle: string;
+}
+/**
+ * Partial theme overrides for the Mention component.
+ */
+export type MentionThemeOverrides = Partial<MentionTheme>;
+/**
+ * Props for the Mention component.
+ */
+export interface MentionProps extends Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, "onChange" | "value" | "defaultValue"> {
+    /** Multiple trigger configurations (e.g. '@' for users, '#' for tags) */
+    triggers?: MentionTrigger[];
+    /** Simple API: suggestions for the default '@' trigger */
+    suggestions?: MentionSuggestion[];
+    /** Simple API: async search callback for the default '@' trigger */
+    onSearch?: (query: string) => void;
+    /** Controlled value */
+    value?: string;
+    /** Uncontrolled default value */
+    defaultValue?: string;
+    /** Change callback with the full text value */
+    onChange?: (value: string) => void;
+    /** Callback when a suggestion is selected */
+    onMentionSelect?: (suggestion: MentionSuggestion, trigger: string) => void;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Size variant */
+    size?: MentionSize;
+    /** Maximum number of suggestions shown */
+    maxSuggestions?: number;
+    /** Additional className for the textarea */
+    className?: string;
+    /** Additional className for the wrapper */
+    wrapperClassName?: string;
+    /** Additional className for the dropdown */
+    dropdownClassName?: string;
+    /** Theme overrides */
+    theme?: MentionThemeOverrides;
+    /** Whether the mention input is disabled */
+    disabled?: boolean;
+    /** Custom renderer for suggestion items */
+    renderSuggestion?: (suggestion: MentionSuggestion, isHighlighted: boolean, trigger: string) => React.ReactNode;
+    /** Message shown when no suggestions match */
+    emptyMessage?: string;
+    /** Whether a search is currently loading */
+    loading?: boolean;
+}

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

@@ -0,0 +1,3 @@
+export { Mention } from "./Mention";
+export type { MentionProps, MentionSuggestion, MentionTrigger, MentionSize, MentionTheme, MentionThemeOverrides, } from "./Mention.types";
+export { mentionTheme } from "./Mention.theme";

package/dist/components/forms/Radio/Radio.js

@@ -1,28 +1,24 @@
 import { jsxs, jsx } from 'react/jsx-runtime';
-import React__default, { useState } from 'react';
+import React__default from 'react';
 import { radioTheme } from './Radio.theme.js';
-import { FormLabel } from '../FormLabel/FormLabel.js';
+import { formLabelTheme } from '../FormLabel/FormLabel.theme.js';
 import { cn } from '../../../utils/cn.js';
 
 /**
  * Radio component for selecting one option from a group
  */
-const Radio = React__default.forwardRef(({ id, name, value, checked: controlledChecked, onChange, label, description, state = "default", size = "md", className, ...restProps }, ref) => {
-    const [internalChecked, setInternalChecked] = useState(false);
-    // Determine if component is controlled or uncontrolled
-    const isControlled = controlledChecked !== undefined;
-    const isChecked = isControlled ? controlledChecked : internalChecked;
-    // Derive state flags
+const Radio = React__default.forwardRef(({ id, name, value, checked, defaultChecked, onChange, label, description, state = "default", size = "md", className, ...restProps }, ref) => {
+    const isControlled = checked !== undefined;
     const isDisabled = state === "disabled";
     const handleChange = (e) => {
         if (isDisabled)
             return;
-        if (!isControlled) {
-            setInternalChecked(e.target.checked);
-        }
         onChange === null || onChange === void 0 ? void 0 : onChange(e.target.checked, value);
     };
-    return (jsxs("div", { className: cn(radioTheme.baseStyle, className), ...restProps, children: [jsxs("div", { className: cn(radioTheme.inputContainerStyle, radioTheme.sizes[size]), children: [jsx("input", { ref: ref, type: "radio", id: id, name: name, value: value, checked: isChecked, onChange: handleChange, disabled: isDisabled, "aria-describedby": description ? `${id}-description` : undefined, "data-state": isDisabled ? "disabled" : "default", className: cn(radioTheme.inputStyle, radioTheme.sizes[size]) }), isChecked && (jsx("div", { className: cn(radioTheme.dotStyle, size === "sm" ? "size-2" : "size-3", "opacity-100") }))] }), (label || description) && (jsxs("div", { className: "cursor-pointer", children: [label && (jsx(FormLabel, { htmlFor: id, className: "!mb-0", state: state, children: label })), description && (jsx("div", { id: `${id}-description`, className: radioTheme.descriptionStyle, children: description }))] }))] }));
+    const inputProps = isControlled
+        ? { checked }
+        : { defaultChecked };
+    return (jsxs("div", { className: cn(radioTheme.baseStyle, className), ...restProps, children: [jsxs("div", { className: cn(radioTheme.inputContainerStyle, radioTheme.sizes[size]), children: [jsx("input", { ref: ref, type: "radio", id: id, name: name, value: value, ...inputProps, onChange: handleChange, disabled: isDisabled, "aria-describedby": description ? `${id}-description` : undefined, "data-state": isDisabled ? "disabled" : "default", className: cn("peer", radioTheme.inputStyle, radioTheme.sizes[size]) }), jsx("div", { className: cn(radioTheme.dotStyle, size === "sm" ? "size-2.5 top-0.25" : "size-3") })] }), (label || description) && (jsxs("label", { htmlFor: id, className: cn("cursor-pointer", isDisabled && "cursor-not-allowed"), children: [label && (jsx("span", { className: cn(formLabelTheme.baseStyle, formLabelTheme.stateStyles[state], "mb-0"), children: label })), description && (jsx("div", { id: `${id}-description`, className: radioTheme.descriptionStyle, children: description }))] }))] }));
 });
 Radio.displayName = "Radio";