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

package/dist/components/core/Tabs/Tabs.types.d.ts

@@ -23,8 +23,8 @@ export type TabsOrientation = "horizontal";
  *     <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
  *     <Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
  *   </Tabs.List>
- *   <Tabs.Content value="tab1">Content 1</Tabs.Content>
- *   <Tabs.Content value="tab2">Content 2</Tabs.Content>
+ *   <Tabs.Body value="tab1">Content 1</Tabs.Body>
+ *   <Tabs.Body value="tab2">Content 2</Tabs.Body>
  * </Tabs>
  *
  * // Uncontrolled mode
@@ -46,7 +46,7 @@ export interface TabsProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'o
     size?: TabsSize;
     /** Whether all tabs are disabled - individual triggers can also be disabled */
     disabled?: boolean;
-    /** Children components - typically Tabs.List and Tabs.Content components */
+    /** Children components - typically Tabs.List and Tabs.Body components */
     children?: React.ReactNode;
     /**
      * Force dark mode styling for the component. Use when placing the component
@@ -98,20 +98,20 @@ export interface TabsTriggerProps extends React.HTMLAttributes<HTMLButtonElement
     'aria-label'?: string;
 }
 /**
- * TabsContent component props - content panel for each tab
+ * TabsBody component props - content panel for each tab
  * @example
  * ```tsx
- * <Tabs.Content value="profile">
+ * <Tabs.Body value="profile">
  *   <UserProfile data={profileData} />
- * </Tabs.Content>
+ * </Tabs.Body>
  *
  * // Force mount content for performance or state preservation
- * <Tabs.Content value="settings" forceMount>
+ * <Tabs.Body value="settings" forceMount>
  *   <SettingsForm /> // Form state preserved when tab is inactive
- * </Tabs.Content>
+ * </Tabs.Body>
  * ```
  */
-export interface TabsContentProps extends React.HTMLAttributes<HTMLDivElement> {
+export interface TabsBodyProps extends React.HTMLAttributes<HTMLDivElement> {
     /** The value that corresponds to a TabsTrigger value - determines when content is shown */
     value: string;
     /** Whether to keep content mounted in DOM when inactive (useful for preserving form state) */
@@ -139,4 +139,8 @@ export interface TabsContextValue {
     registerTrigger: (value: string, element: HTMLButtonElement) => void;
     /** Unregister a tab trigger when it unmounts */
     unregisterTrigger: (value: string) => void;
+    /** Unique prefix scoping DOM IDs to this Tabs instance */
+    instanceId: string;
+    /** Whether the user has switched tabs yet (false until the first change). Used to suppress content animation on mount. */
+    hasSwitched: boolean;
 }

package/dist/components/core/Tabs/TabsBody.d.ts

@@ -0,0 +1,6 @@
+import React from "react";
+import { TabsBodyProps } from "./Tabs.types";
+/**
+ * TabsBody component displays content panels for tabs with directional fade animations
+ */
+export declare const TabsBody: React.ForwardRefExoticComponent<TabsBodyProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/core/Tabs/{TabsContent.js → TabsBody.js}

@@ -1,27 +1,28 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import React__default, { useMemo } from 'react';
 import { useReducedMotion, motion, AnimatePresence } from 'motion/react';
 import { cn } from '../../../utils/cn.js';
 import { tabsTheme } from './Tabs.theme.js';
 import { useTabsContext } from './TabsContext.js';
-import { getTabsContentVariants } from './Tabs.animations.js';
+import { getTabsBodyVariants } from './Tabs.animations.js';
 
 /**
- * TabsContent component displays content panels for tabs with directional fade animations
+ * TabsBody component displays content panels for tabs with directional fade animations
  */
-const TabsContent = React__default.forwardRef(({ value, forceMount = false, children, className, ...props }, ref) => {
-    const { value: selectedValue, orientation } = useTabsContext();
+const TabsBody = React__default.forwardRef(({ value, forceMount = false, children, className, ...props }, ref) => {
+    const { value: selectedValue, orientation, instanceId, hasSwitched } = useTabsContext();
     const shouldReduceMotion = useReducedMotion();
     // Check if we're in Storybook and should disable animations
     const isInStorybook = typeof window !== 'undefined' && window.__STORYBOOK_DISABLE_ANIMATIONS__;
-    const shouldDisableAnimations = !!shouldReduceMotion || isInStorybook;
+    const shouldDisableAnimations = !!shouldReduceMotion || !!isInStorybook;
     const isSelected = value === selectedValue;
     const shouldRender = forceMount || isSelected;
     // Compute animation variants without a global cache (HMR-safe)
-    const contentVariants = useMemo(() => getTabsContentVariants(shouldDisableAnimations), [shouldDisableAnimations]);
+    const contentVariants = useMemo(() => getTabsBodyVariants(shouldDisableAnimations), [shouldDisableAnimations]);
     // For forceMount, we handle visibility differently to preserve DOM
     if (forceMount) {
-        return (jsx(motion.div, { ref: ref, role: "tabpanel", "aria-labelledby": `${value}-tab`, id: `${value}-content`, tabIndex: 0, className: cn(tabsTheme.contentStyle, !isSelected && "hidden", // Hide when not selected but force mounted
+        return (jsx(motion.div, { ref: ref, role: "tabpanel", "aria-labelledby": `${instanceId}-${value}-tab`, id: `${instanceId}-${value}-content`, tabIndex: 0, className: cn(tabsTheme.bodyStyle, !isSelected && "hidden", // Hide when not selected but force mounted
             className // User overrides take precedence
             ), "data-state": isSelected ? "active" : "inactive", "data-orientation": orientation, style: {
                 // Ensure proper stacking context for animations
@@ -32,19 +33,21 @@ const TabsContent = React__default.forwardRef(({ value, forceMount = false, chil
     if (!shouldRender) {
         return null;
     }
-    // Determine animation props (user props will override due to spread order)
+    // Determine animation props (user props will override due to spread order).
+    // Until the user switches tabs, the panel snaps in (initial=false) so it does
+    // not animate on mount / page load — only actual tab changes animate.
     const animationProps = shouldDisableAnimations ? {} : {
-        initial: "initial",
+        initial: hasSwitched ? "initial" : false,
         animate: "animate",
         exit: "exit",
         variants: contentVariants,
     };
-    return (jsx(AnimatePresence, { mode: "wait", children: isSelected && (jsx(motion.div, { ref: ref, role: "tabpanel", "aria-labelledby": `${value}-tab`, id: `${value}-content`, tabIndex: 0, className: cn(tabsTheme.contentStyle, className // User overrides take precedence
+    return (jsx(AnimatePresence, { mode: "wait", children: isSelected && (jsx(motion.div, { ref: ref, role: "tabpanel", "aria-labelledby": `${instanceId}-${value}-tab`, id: `${instanceId}-${value}-content`, tabIndex: 0, className: cn(tabsTheme.bodyStyle, className // User overrides take precedence
             ), "data-state": "active", "data-orientation": orientation, style: {
                 // Ensure proper stacking context for animations
                 position: "relative",
             }, ...animationProps, ...props, children: children }, `content-${value}`)) }));
 });
-TabsContent.displayName = "TabsContent";
+TabsBody.displayName = "Tabs.Body";
 
-export { TabsContent };
+export { TabsBody };

package/dist/components/core/Tabs/TabsContext.js

@@ -1,3 +1,4 @@
+"use client";
 import { createContext, useContext } from 'react';
 
 /**

package/dist/components/core/Tabs/TabsList.js

@@ -1,5 +1,6 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
-import React__default, { useState, useRef, useMemo, useEffect } from 'react';
+import React__default, { useState, useRef, useCallback, useEffect, useMemo } from 'react';
 import { useReducedMotion, motion } from 'motion/react';
 import { cn } from '../../../utils/cn.js';
 import { tabsTheme } from './Tabs.theme.js';
@@ -18,26 +19,24 @@ const TabsList = React__default.forwardRef(({ children, className, ...props }, r
     // Ref to access the list element for calculations
     const listRef = useRef(null);
     // Calculate underline position based on active tab
-    const updateUnderlinePosition = useMemo(() => {
-        return () => {
-            if (!activeValue || !listRef.current) {
-                setShowUnderline(false);
-                return;
-            }
-            // Find the active trigger element
-            const activeTrigger = listRef.current.querySelector(`[data-value="${activeValue}"]`);
-            if (!activeTrigger) {
-                setShowUnderline(false);
-                return;
-            }
-            // Get the position relative to the list container
-            const listRect = listRef.current.getBoundingClientRect();
-            const triggerRect = activeTrigger.getBoundingClientRect();
-            const left = triggerRect.left - listRect.left;
-            const width = triggerRect.width;
-            setUnderlinePosition({ left, width });
-            setShowUnderline(true);
-        };
+    const updateUnderlinePosition = useCallback(() => {
+        if (!activeValue || !listRef.current) {
+            setShowUnderline(false);
+            return;
+        }
+        // Find the active trigger element
+        const activeTrigger = listRef.current.querySelector(`[data-value="${activeValue}"]`);
+        if (!activeTrigger) {
+            setShowUnderline(false);
+            return;
+        }
+        // Get the position relative to the list container
+        const listRect = listRef.current.getBoundingClientRect();
+        const triggerRect = activeTrigger.getBoundingClientRect();
+        const left = triggerRect.left - listRect.left;
+        const width = triggerRect.width;
+        setUnderlinePosition({ left, width });
+        setShowUnderline(true);
     }, [activeValue]);
     // Update underline position when active value changes or on mount
     useEffect(() => {

package/dist/components/core/Tabs/TabsTrigger.js

@@ -1,5 +1,6 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
-import React__default, { useMemo, useCallback, useEffect } from 'react';
+import React__default, { useRef, useEffect, useMemo, useCallback } from 'react';
 import { useReducedMotion, motion } from 'motion/react';
 import { cn } from '../../../utils/cn.js';
 import { tabsTheme } from './Tabs.theme.js';
@@ -10,11 +11,14 @@ import { getTabsTriggerVariants } from './Tabs.animations.js';
  * TabsTrigger component displays individual tab headers with optional animations
  */
 const TabsTrigger = React__default.forwardRef(({ value, disabled = false, children, className, onClick, onKeyDown, ...props }, ref) => {
-    const { value: selectedValue, onValueChange, orientation, size, disabled: contextDisabled, registerTrigger, unregisterTrigger } = useTabsContext();
+    const { value: selectedValue, onValueChange, orientation, size, disabled: contextDisabled, registerTrigger, unregisterTrigger, instanceId } = useTabsContext();
     const shouldReduceMotion = useReducedMotion();
-    // Check if we're in Storybook and should disable animations
-    const isInStorybook = typeof window !== 'undefined' && window.__STORYBOOK_DISABLE_ANIMATIONS__;
-    const shouldDisableAnimations = !!shouldReduceMotion || isInStorybook;
+    // Check if we're in Storybook — evaluated after mount to avoid SSR hydration mismatch
+    const isInStorybookRef = useRef(false);
+    useEffect(() => {
+        isInStorybookRef.current = typeof window !== 'undefined' && !!window.__STORYBOOK_DISABLE_ANIMATIONS__;
+    }, []);
+    const shouldDisableAnimations = !!shouldReduceMotion || !!isInStorybookRef.current;
     // Memoize derived state flags for performance
     const derivedState = useMemo(() => ({
         isSelected: value === selectedValue,
@@ -51,7 +55,6 @@ const TabsTrigger = React__default.forwardRef(({ value, disabled = false, childr
     }, [isDisabled, onValueChange, value, onClick]);
     // Enhanced keyboard navigation handler with error handling
     const handleKeyDown = useCallback((event) => {
-        var _a, _b;
         // Handle keyboard navigation for tabs
         if (!isDisabled) {
             try {
@@ -59,39 +62,74 @@ const TabsTrigger = React__default.forwardRef(({ value, disabled = false, childr
                     case "ArrowLeft":
                     case "ArrowUp":
                         event.preventDefault();
-                        // Move to previous tab - focus previous trigger
-                        const prevTrigger = event.currentTarget.previousElementSibling;
-                        if (prevTrigger && prevTrigger.tagName === 'BUTTON' && !prevTrigger.disabled) {
-                            prevTrigger.focus();
-                            prevTrigger.click();
+                        // Move to previous *enabled* tab, skipping over any number of
+                        // consecutive disabled triggers and wrapping around the start
+                        // (same enabled-only trigger list Home/End use below).
+                        {
+                            const tabList = event.currentTarget.parentElement;
+                            const allTabs = tabList
+                                ? Array.from(tabList.querySelectorAll('[role="tab"]:not([disabled])'))
+                                : [];
+                            const currentIndex = allTabs.indexOf(event.currentTarget);
+                            if (allTabs.length > 0 && currentIndex !== -1) {
+                                const prevIndex = (currentIndex - 1 + allTabs.length) % allTabs.length;
+                                const prevTrigger = allTabs[prevIndex];
+                                if (prevTrigger) {
+                                    prevTrigger.focus();
+                                    prevTrigger.click();
+                                }
+                            }
                         }
                         break;
                     case "ArrowRight":
                     case "ArrowDown":
                         event.preventDefault();
-                        // Move to next tab - focus next trigger
-                        const nextTrigger = event.currentTarget.nextElementSibling;
-                        if (nextTrigger && nextTrigger.tagName === 'BUTTON' && !nextTrigger.disabled) {
-                            nextTrigger.focus();
-                            nextTrigger.click();
+                        // Move to next *enabled* tab, skipping over any number of
+                        // consecutive disabled triggers and wrapping around the end.
+                        {
+                            const tabList = event.currentTarget.parentElement;
+                            const allTabs = tabList
+                                ? Array.from(tabList.querySelectorAll('[role="tab"]:not([disabled])'))
+                                : [];
+                            const currentIndex = allTabs.indexOf(event.currentTarget);
+                            if (allTabs.length > 0 && currentIndex !== -1) {
+                                const nextIndex = (currentIndex + 1) % allTabs.length;
+                                const nextTrigger = allTabs[nextIndex];
+                                if (nextTrigger) {
+                                    nextTrigger.focus();
+                                    nextTrigger.click();
+                                }
+                            }
                         }
                         break;
                     case "Home":
                         event.preventDefault();
-                        // Move to first tab
-                        const firstTrigger = (_a = event.currentTarget.parentElement) === null || _a === void 0 ? void 0 : _a.firstElementChild;
-                        if (firstTrigger && firstTrigger.tagName === 'BUTTON' && !firstTrigger.disabled) {
-                            firstTrigger.focus();
-                            firstTrigger.click();
+                        // Move to first tab — use role="tab" to skip the sliding underline element
+                        {
+                            const tabList = event.currentTarget.parentElement;
+                            const allTabs = tabList
+                                ? Array.from(tabList.querySelectorAll('[role="tab"]:not([disabled])'))
+                                : [];
+                            const firstTrigger = allTabs[0];
+                            if (firstTrigger) {
+                                firstTrigger.focus();
+                                firstTrigger.click();
+                            }
                         }
                         break;
                     case "End":
                         event.preventDefault();
-                        // Move to last tab
-                        const lastTrigger = (_b = event.currentTarget.parentElement) === null || _b === void 0 ? void 0 : _b.lastElementChild;
-                        if (lastTrigger && lastTrigger.tagName === 'BUTTON' && !lastTrigger.disabled) {
-                            lastTrigger.focus();
-                            lastTrigger.click();
+                        // Move to last tab — use role="tab" to skip the sliding underline element
+                        {
+                            const tabList = event.currentTarget.parentElement;
+                            const allTabs = tabList
+                                ? Array.from(tabList.querySelectorAll('[role="tab"]:not([disabled])'))
+                                : [];
+                            const lastTrigger = allTabs[allTabs.length - 1];
+                            if (lastTrigger) {
+                                lastTrigger.focus();
+                                lastTrigger.click();
+                            }
                         }
                         break;
                 }
@@ -114,18 +152,23 @@ const TabsTrigger = React__default.forwardRef(({ value, disabled = false, childr
     }, [size]);
     // Generate default aria-label for icon-only triggers if not provided (fallback only)
     const ariaLabel = props["aria-label"] || undefined;
-    // Register/unregister this trigger for underline positioning
-    useEffect(() => {
-        // Register with a slight delay to ensure DOM is ready
-        const timeoutId = setTimeout(() => {
-            if (ref && typeof ref === 'object' && ref.current) {
-                registerTrigger(value, ref.current);
-            }
-        }, 0);
-        return () => {
-            clearTimeout(timeoutId);
+    // Callback ref that registers/unregisters the trigger for underline positioning.
+    // Using a callback ref ensures registration fires whenever the DOM node mounts,
+    // not just when the ref object identity changes.
+    const triggerRef = useCallback((node) => {
+        if (node) {
+            registerTrigger(value, node);
+        }
+        else {
             unregisterTrigger(value);
-        };
+        }
+        // Forward to the outer ref passed by the consumer, if any
+        if (typeof ref === 'function') {
+            ref(node);
+        }
+        else if (ref) {
+            ref.current = node;
+        }
     }, [value, registerTrigger, unregisterTrigger, ref]);
     // Determine animation props (user props will override due to spread order)
     const animationProps = shouldDisableAnimations ? {} : {
@@ -133,7 +176,7 @@ const TabsTrigger = React__default.forwardRef(({ value, disabled = false, childr
         whileTap: !isDisabled ? "tap" : undefined,
         variants: triggerVariants,
     };
-    return (jsx(motion.button, { ref: ref, type: "button", role: "tab", "aria-selected": isSelected, "aria-controls": `${value}-content`, id: `${value}-tab`, tabIndex: isSelected ? 0 : -1, disabled: isDisabled, className: cn(themeClasses.triggerStyle, themeClasses.sizeStyle, className // User overrides take precedence
+    return (jsx(motion.button, { ref: triggerRef, type: "button", role: "tab", "aria-selected": isSelected, "aria-controls": `${instanceId}-${value}-content`, id: `${instanceId}-${value}-tab`, tabIndex: isSelected ? 0 : -1, disabled: isDisabled, className: cn(themeClasses.triggerStyle, themeClasses.sizeStyle, className // User overrides take precedence
         ), onClick: handleClick, onKeyDown: handleKeyDown, "data-value": value, "data-state": isSelected ? "active" : "inactive", "data-disabled": isDisabled, "data-orientation": orientation, "aria-disabled": isDisabled || undefined, "aria-label": ariaLabel, ...animationProps, ...props, children: children }));
 });
 TabsTrigger.displayName = "TabsTrigger";

package/dist/components/core/Tabs/index.d.ts

@@ -1,6 +1,6 @@
 export { Tabs } from './Tabs';
 export { TabsList } from './TabsList';
 export { TabsTrigger } from './TabsTrigger';
-export { TabsContent } from './TabsContent';
+export { TabsBody } from './TabsBody';
 export { TabsContext, useTabsContext } from './TabsContext';
-export type { TabsProps, TabsListProps, TabsTriggerProps, TabsContentProps, TabsSize, TabsOrientation, TabsContextValue } from './Tabs.types';
+export type { TabsProps, TabsListProps, TabsTriggerProps, TabsBodyProps, TabsSize, TabsOrientation, TabsContextValue } from './Tabs.types';

package/dist/components/core/Tag/Tag.animations.js

@@ -1,17 +1,4 @@
 const tagVariants = {
-    initial: {
-        scale: 0,
-        opacity: 0,
-    },
-    animate: {
-        scale: 1,
-        opacity: 1,
-        transition: {
-            type: "spring",
-            stiffness: 500,
-            damping: 25,
-        },
-    },
     exit: {
         scale: 0,
         opacity: 0,

package/dist/components/core/Tag/Tag.d.ts

@@ -7,8 +7,8 @@ import { TagProps } from "./Tag.types";
  * @example
  * ```tsx
  * <Tag onRemove={() => handleRemove('tag1')}>JavaScript</Tag>
- * <Tag size="sm" removable={false}>Read Only</Tag>
- * <Tag disabled>Disabled Tag</Tag>
+ * <Tag avatar={{ src: "/avatar.jpg", name: "Alice" }} onRemove={() => {}}>Alice</Tag>
+ * <Tag startContent={<CodeIcon className="size-4" />} onRemove={() => {}}>React</Tag>
  * ```
  */
 export declare const Tag: React.ForwardRefExoticComponent<TagProps & React.RefAttributes<HTMLSpanElement>>;

package/dist/components/core/Tag/Tag.js

@@ -1,8 +1,10 @@
-import { jsxs, jsx } from 'react/jsx-runtime';
+"use client";
+import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
 import React__default from 'react';
 import { motion } from 'motion/react';
 import { XMarkIcon } from '@heroicons/react/24/outline';
 import { cn } from '../../../utils/cn.js';
+import { Avatar } from '../Avatar/Avatar.js';
 import { tagTheme } from './Tag.theme.js';
 import { tagVariants, tagLayoutTransition } from './Tag.animations.js';
 
@@ -13,16 +15,21 @@ import { tagVariants, tagLayoutTransition } from './Tag.animations.js';
  * @example
  * ```tsx
  * <Tag onRemove={() => handleRemove('tag1')}>JavaScript</Tag>
- * <Tag size="sm" removable={false}>Read Only</Tag>
- * <Tag disabled>Disabled Tag</Tag>
+ * <Tag avatar={{ src: "/avatar.jpg", name: "Alice" }} onRemove={() => {}}>Alice</Tag>
+ * <Tag startContent={<CodeIcon className="size-4" />} onRemove={() => {}}>React</Tag>
  * ```
  */
-const Tag = React__default.forwardRef(({ children, size = "md", removable = true, onRemove, disabled = false, className, theme: customTheme, ...props }, ref) => {
+const Tag = React__default.forwardRef(({ children, size = "md", removable = true, onRemove, avatar, startContent, disabled = false, animated = true, className, theme: customTheme, ...props }, ref) => {
     var _a, _b, _c;
     // Merge default theme with custom theme overrides
     const theme = {
         baseStyle: (_a = customTheme === null || customTheme === void 0 ? void 0 : customTheme.baseStyle) !== null && _a !== void 0 ? _a : tagTheme.baseStyle,
         sizes: { ...tagTheme.sizes, ...customTheme === null || customTheme === void 0 ? void 0 : customTheme.sizes },
+        avatarSizes: { ...tagTheme.avatarSizes, ...customTheme === null || customTheme === void 0 ? void 0 : customTheme.avatarSizes },
+        startContentSizes: {
+            ...tagTheme.startContentSizes,
+            ...customTheme === null || customTheme === void 0 ? void 0 : customTheme.startContentSizes,
+        },
         disabledStyle: (_b = customTheme === null || customTheme === void 0 ? void 0 : customTheme.disabledStyle) !== null && _b !== void 0 ? _b : tagTheme.disabledStyle,
         removeButtonStyle: (_c = customTheme === null || customTheme === void 0 ? void 0 : customTheme.removeButtonStyle) !== null && _c !== void 0 ? _c : tagTheme.removeButtonStyle,
         removeIconSizes: {
@@ -30,6 +37,7 @@ const Tag = React__default.forwardRef(({ children, size = "md", removable = true
             ...customTheme === null || customTheme === void 0 ? void 0 : customTheme.removeIconSizes,
         },
     };
+    const hasLeadingContent = !!(avatar || startContent);
     const showRemoveButton = removable && onRemove && !disabled;
     const handleRemove = (e) => {
         e.stopPropagation();
@@ -37,7 +45,41 @@ const Tag = React__default.forwardRef(({ children, size = "md", removable = true
             onRemove();
         }
     };
-    return (jsxs(motion.span, { ref: ref, className: cn(theme.baseStyle, theme.sizes[size], showRemoveButton && "pr-0.5", disabled && theme.disabledStyle, className), layout: true, transition: tagLayoutTransition, variants: tagVariants, initial: "initial", animate: "animate", exit: "exit", "data-size": size, "data-disabled": disabled ? "true" : "false", "data-removable": removable ? "true" : "false", ...props, children: [children, showRemoveButton && (jsx("button", { type: "button", onClick: handleRemove, className: theme.removeButtonStyle, "aria-label": `Remove ${typeof children === "string" ? children : "tag"}`, children: jsx(XMarkIcon, { className: theme.removeIconSizes[size] }) }))] }));
+    // Avatar takes precedence over startContent
+    const renderLeadingContent = () => {
+        if (avatar) {
+            return (jsx("span", { 
+                // leading-[0] collapses the inline line-box strut: the Avatar's
+                // inner circle is inline-flex, so a non-zero line-height adds
+                // descender space below it and pins the circle to the top of a
+                // taller line box — the visible photo then renders ~1.75px high.
+                // Zeroing the line-height makes the 16px circle define the box exactly.
+                className: cn("inline-flex items-center justify-center shrink-0 overflow-hidden rounded-full leading-[0] -ml-0.5", theme.avatarSizes[size]), children: jsx(Avatar, { src: avatar.src, name: avatar.name, fallback: avatar.fallback, initialsCount: avatar.initialsCount, size: "xs", className: "bg-[var(--color-surface-hover)] border  border-[var(--color-border)]" }) }));
+        }
+        if (startContent) {
+            return (jsx("span", { 
+                // leading-[0]: same line-box collapse as the avatar wrapper above,
+                // so inline startContent (icons/emoji) stays vertically centered.
+                className: cn("inline-flex items-center justify-center shrink-0 leading-[0]", theme.startContentSizes[size]), children: startContent }));
+        }
+        return null;
+    };
+    const content = (jsxs(Fragment, { children: [renderLeadingContent(), children, showRemoveButton && (jsx("button", { type: "button", onClick: handleRemove, className: theme.removeButtonStyle, "aria-label": `Remove ${typeof children === "string" ? children : "tag"}`, children: jsx(XMarkIcon, { className: theme.removeIconSizes[size] }) }))] }));
+    const sharedProps = {
+        ref,
+        className: cn(theme.baseStyle, theme.sizes[size], hasLeadingContent && "pl-1", showRemoveButton && "pr-0.5", disabled && theme.disabledStyle, className),
+        "data-size": size,
+        "data-disabled": disabled ? "true" : "false",
+        "data-removable": removable ? "true" : "false",
+        "data-has-avatar": avatar ? "true" : "false",
+        ...props,
+    };
+    // Plain span when animation is opted out (e.g. inside a contentEditable host,
+    // where Framer-Motion's layout FLIP fights the caret on every keystroke).
+    if (!animated) {
+        return jsx("span", { ...sharedProps, children: content });
+    }
+    return (jsx(motion.span, { ...sharedProps, layout: true, transition: tagLayoutTransition, variants: tagVariants, exit: "exit", children: content }));
 });
 Tag.displayName = "Tag";
 

package/dist/components/core/Tag/Tag.theme.js

@@ -1,14 +1,27 @@
 const tagTheme = {
-    baseStyle: "inline-flex items-center gap-0.5 font-medium rounded-full " +
-        "bg-white dark:bg-[var(--color-background-secondary)] border border-[var(--color-border)] " +
+    baseStyle: "inline-flex items-center gap-1.5 font-medium rounded-full " +
+        "bg-[var(--color-surface-raised)] border border-[var(--color-border)] " +
         "text-[var(--color-text-primary)]",
     sizes: {
-        sm: "text-xs px-2.5 py-0.5",
-        md: "text-sm px-2.5 py-0.5",
+        sm: "text-xs px-2 py-0.5",
+        md: "text-sm px-2 pl-2.5 py-0.5",
+    },
+    // No left margin here: the avatar/icon's left inset is owned by the tag's
+    // `pl-1` (applied when there's leading content), not by a per-size `ml-*`.
+    // Stacking `ml-*` on top of that padding pushed the avatar too far from the
+    // left edge and produced a lopsided pill. The avatar-to-text gap is handled
+    // by the base `gap-1`, not by this margin.
+    avatarSizes: {
+        sm: "size-4",
+        md: "size-5",
+    },
+    startContentSizes: {
+        sm: "",
+        md: "",
     },
     disabledStyle: "opacity-50 cursor-not-allowed",
-    removeButtonStyle: "inline-flex items-center justify-center rounded-full p-1 " +
-        "hover:bg-[var(--color-background-quaternary)] " +
+    removeButtonStyle: "inline-flex items-center justify-center rounded-full p-0.5 -ml-1 " +
+        "hover:bg-[var(--color-surface-hover)] " +
         "text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] " +
         "transition-all duration-300 cursor-pointer focus:outline-none " +
         "focus-visible:ring-2 focus-visible:ring-[var(--color-primary)]",

package/dist/components/core/Tag/Tag.types.d.ts

@@ -1,4 +1,4 @@
-import React from "react";
+import React, { ReactNode } from "react";
 /**
  * Tag component props
  */
@@ -11,8 +11,32 @@ export interface TagProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, "o
     removable?: boolean;
     /** Callback when the remove button is clicked */
     onRemove?: () => void;
+    /**
+     * Avatar configuration — renders a sized avatar to the left of the label.
+     * The component controls avatar sizing and styling internally.
+     * Takes precedence over startContent.
+     */
+    avatar?: {
+        src?: string;
+        name: string;
+        fallback?: ReactNode;
+        initialsCount?: number;
+    };
+    /**
+     * Generic content to display at the start (before the label).
+     * Use for icons, emojis, or any custom ReactNode.
+     * Ignored when avatar is provided.
+     */
+    startContent?: ReactNode;
     /** Whether the tag is disabled */
     disabled?: boolean;
+    /**
+     * Whether to render with motion (layout + enter/exit animation). Default true.
+     * Set `false` to render a plain `<span>` — required when a Tag lives inside a
+     * contentEditable host (e.g. Mention chips), where Framer-Motion's `layout`
+     * FLIP re-measurement fights the browser's caret/selection on every keystroke.
+     */
+    animated?: boolean;
     /** Additional class name for the tag */
     className?: string;
     /** Theme overrides */
@@ -24,6 +48,10 @@ export interface TagTheme {
     baseStyle: string;
     /** Size-specific styles */
     sizes: Record<TagSize, string>;
+    /** Avatar sizes for each tag size */
+    avatarSizes: Record<TagSize, string>;
+    /** Start content sizes for each tag size */
+    startContentSizes: Record<TagSize, string>;
     /** Disabled state style */
     disabledStyle: string;
     /** Remove button style */
@@ -34,6 +62,8 @@ export interface TagTheme {
 export interface TagThemeOverrides {
     baseStyle?: string;
     sizes?: Partial<Record<TagSize, string>>;
+    avatarSizes?: Partial<Record<TagSize, string>>;
+    startContentSizes?: Partial<Record<TagSize, string>>;
     disabledStyle?: string;
     removeButtonStyle?: string;
     removeIconSizes?: Partial<Record<TagSize, string>>;

package/dist/components/core/Toast/Toast.animations.d.ts

@@ -9,16 +9,17 @@ export declare const toastAnimations: {
         scale: number;
         transition: {
             duration: number;
+            ease: "easeIn";
         };
     };
     transition: {
         type: "spring";
         stiffness: number;
         damping: number;
-        mass: number;
     };
 };
-export declare const getToastStackingAnimation: (index: number, totalToasts: number, isExpanded: boolean, expandedY?: number) => {
+import { ToastPosition } from "./Toast.types";
+export declare const getToastStackingAnimation: (index: number, totalToasts: number, isExpanded: boolean, expandedY?: number, position?: ToastPosition) => {
     y?: undefined;
     scale?: undefined;
     zIndex?: undefined;