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

package/dist/components/core/Toast/ToastProvider.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import React__default, { createContext, useState, useCallback, useMemo, useContext } from 'react';
 import { AnimatePresence } from 'motion/react';
@@ -24,7 +25,7 @@ const ToastProvider = ({ children, position = 'top-right', maxToasts = 5, defaul
     const hoverTimeoutRef = React__default.useRef(null);
     const addToast = useCallback((toastData) => {
         var _a;
-        const id = Math.random().toString(36).substring(2, 9);
+        const id = crypto.randomUUID();
         const newToast = {
             ...toastData,
             id,
@@ -91,7 +92,11 @@ const ToastProvider = ({ children, position = 'top-right', maxToasts = 5, defaul
         removeToast,
         removeAllToasts,
     }), [toasts, addToast, removeToast, removeAllToasts]);
-    return (jsxs(ToastContext.Provider, { value: contextValue, children: [children, isClient && createPortal(jsx("div", { className: cn(toastTheme.containerStyle, positionStyles[position]), "aria-live": "polite", "aria-label": "Notifications", children: jsx("div", { className: "relative w-80", style: { paddingBottom: isHovered && toasts.length > 1 ? totalExpandedHeight : undefined }, onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, children: jsx(AnimatePresence, { mode: "popLayout", children: toasts.map((toast, index) => (jsx(Toast, { toast: toast, onDismiss: removeToast, index: index, isExpanded: isHovered, totalToasts: toasts.length, onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, onHeightChange: handleToastHeight, expandedOffset: getExpandedOffset(index), darkMode: darkMode }, toast.id))) }) }) }), document.body)] }));
+    const portalTarget = isClient ? document.body : null;
+    return (jsxs(ToastContext.Provider, { value: contextValue, children: [children, portalTarget ? createPortal(jsx("div", { className: cn(toastTheme.containerStyle, positionStyles[position]), "aria-live": "polite", "aria-label": "Notifications", children: jsx("div", { className: "relative w-80", style: {
+                        paddingBottom: !position.startsWith("bottom") && isHovered && toasts.length > 1 ? totalExpandedHeight : undefined,
+                        paddingTop: position.startsWith("bottom") && isHovered && toasts.length > 1 ? totalExpandedHeight : undefined,
+                    }, onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, children: jsx(AnimatePresence, { mode: "popLayout", children: toasts.map((toast, index) => (jsx(Toast, { toast: toast, onDismiss: removeToast, index: index, isExpanded: isHovered, totalToasts: toasts.length, onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, onHeightChange: handleToastHeight, expandedOffset: getExpandedOffset(index), darkMode: darkMode, position: position }, toast.id))) }) }) }), portalTarget) : null] }));
 };
 const useToastContext = () => {
     const context = useContext(ToastContext);

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

@@ -1,5 +1,5 @@
 export { Toast } from './Toast';
 export { ToastProvider, useToastContext } from './ToastProvider';
 export { useToast } from './useToast';
-export type { ToastProps, ToastData, ToastProviderProps, ToastTheme, ToastThemeOverrides, ToastVariant, UseToastReturn, UseToastOptions, } from './Toast.types';
+export type { ToastProps, ToastData, ToastProviderProps, ToastTheme, UseToastReturn, UseToastOptions, } from './Toast.types';
 export { toastTheme } from './Toast.theme';

package/dist/components/core/Toast/useToast.js

@@ -1,5 +1,6 @@
+"use client";
 import React__default, { useCallback } from 'react';
-import { InformationCircleIcon, ExclamationTriangleIcon, XCircleIcon, CheckCircleIcon } from '@heroicons/react/24/solid';
+import { Info, Warning, XCircle, CheckCircle } from '@phosphor-icons/react';
 import { useToastContext } from './ToastProvider.js';
 
 const createSemanticIcon = (IconComponent, colorClass) => {
@@ -12,7 +13,6 @@ const useToast = () => {
     const toast = useCallback((title, options) => {
         return addToast({
             title,
-            variant: options === null || options === void 0 ? void 0 : options.variant,
             state: (options === null || options === void 0 ? void 0 : options.state) || 'default',
             subtitle: options === null || options === void 0 ? void 0 : options.subtitle,
             duration: options === null || options === void 0 ? void 0 : options.duration,
@@ -24,56 +24,55 @@ const useToast = () => {
     const success = useCallback((title, options) => {
         return addToast({
             title,
-            variant: options === null || options === void 0 ? void 0 : options.variant,
             state: (options === null || options === void 0 ? void 0 : options.state) || 'default',
+            color: 'success',
             subtitle: options === null || options === void 0 ? void 0 : options.subtitle,
             duration: options === null || options === void 0 ? void 0 : options.duration,
             dismissible: options === null || options === void 0 ? void 0 : options.dismissible,
             action: options === null || options === void 0 ? void 0 : options.action,
-            icon: (options === null || options === void 0 ? void 0 : options.icon) || createSemanticIcon(CheckCircleIcon, 'text-[var(--color-success)]'),
+            icon: (options === null || options === void 0 ? void 0 : options.icon) || createSemanticIcon(CheckCircle, 'text-[var(--color-success)]'),
         });
     }, [addToast]);
     const error = useCallback((title, options) => {
         return addToast({
             title,
-            variant: options === null || options === void 0 ? void 0 : options.variant,
             state: (options === null || options === void 0 ? void 0 : options.state) || 'default',
+            color: 'danger',
             subtitle: options === null || options === void 0 ? void 0 : options.subtitle,
             duration: options === null || options === void 0 ? void 0 : options.duration,
             dismissible: options === null || options === void 0 ? void 0 : options.dismissible,
             action: options === null || options === void 0 ? void 0 : options.action,
-            icon: (options === null || options === void 0 ? void 0 : options.icon) || createSemanticIcon(XCircleIcon, 'text-[var(--color-danger)]'),
+            icon: (options === null || options === void 0 ? void 0 : options.icon) || createSemanticIcon(XCircle, 'text-[var(--color-danger)]'),
         });
     }, [addToast]);
     const warning = useCallback((title, options) => {
         return addToast({
             title,
-            variant: options === null || options === void 0 ? void 0 : options.variant,
             state: (options === null || options === void 0 ? void 0 : options.state) || 'default',
+            color: 'warning',
             subtitle: options === null || options === void 0 ? void 0 : options.subtitle,
             duration: options === null || options === void 0 ? void 0 : options.duration,
             dismissible: options === null || options === void 0 ? void 0 : options.dismissible,
             action: options === null || options === void 0 ? void 0 : options.action,
-            icon: (options === null || options === void 0 ? void 0 : options.icon) || createSemanticIcon(ExclamationTriangleIcon, 'text-[var(--color-warning)]'),
+            icon: (options === null || options === void 0 ? void 0 : options.icon) || createSemanticIcon(Warning, 'text-[var(--color-warning)]'),
         });
     }, [addToast]);
     const info = useCallback((title, options) => {
         return addToast({
             title,
-            variant: options === null || options === void 0 ? void 0 : options.variant,
             state: (options === null || options === void 0 ? void 0 : options.state) || 'default',
+            color: 'primary',
             subtitle: options === null || options === void 0 ? void 0 : options.subtitle,
             duration: options === null || options === void 0 ? void 0 : options.duration,
             dismissible: options === null || options === void 0 ? void 0 : options.dismissible,
             action: options === null || options === void 0 ? void 0 : options.action,
-            icon: (options === null || options === void 0 ? void 0 : options.icon) || createSemanticIcon(InformationCircleIcon, 'text-[var(--color-primary)]'),
+            icon: (options === null || options === void 0 ? void 0 : options.icon) || createSemanticIcon(Info, 'text-[var(--color-primary)]'),
         });
     }, [addToast]);
     const loading = useCallback((title, options) => {
         var _a, _b;
         return addToast({
             title,
-            variant: options === null || options === void 0 ? void 0 : options.variant,
             state: 'loading',
             subtitle: options === null || options === void 0 ? void 0 : options.subtitle,
             duration: (_a = options === null || options === void 0 ? void 0 : options.duration) !== null && _a !== void 0 ? _a : 0, // Loading toasts don't auto-dismiss by default

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

@@ -1,64 +1,26 @@
-// Define optimized spring configurations
-const springConfig = {
-    type: "spring",
-    stiffness: 500,
-    damping: 30
-};
+"use client";
+import '../../../theme/ThemeContext.js';
+import '../../../theme/SurfaceContext.js';
+import { getOverlayMenuVariants } from '../../../theme/animations.js';
+
 /**
  * Base animation variants for the tooltip - optimized for smooth positioning
  */
-const baseTooltipVariants = {
-    initial: {
-        opacity: 0,
-        transition: { duration: 0.1 }
-    },
-    animate: {
-        opacity: 1,
-        transition: { ...springConfig, duration: 0.2 }
-    },
-    exit: {
-        opacity: 0,
-        transition: { duration: 0.15, damping: 35 }
-    }
-};
+const baseTooltipVariants = getOverlayMenuVariants('top', {
+    scale: 0.98,
+    shift: 4,
+});
 /**
  * Get animation variants based on tooltip placement
  * @param placement - Tooltip placement (top, right, bottom, left)
  * @returns Animation variants for the specified placement
  */
 const getTooltipVariants = (placement) => {
-    switch (placement) {
-        case 'top':
-            return {
-                ...baseTooltipVariants,
-                initial: { ...baseTooltipVariants.initial, y: 2 },
-                animate: { ...baseTooltipVariants.animate, y: 0 },
-                exit: { ...baseTooltipVariants.exit, y: 2 }
-            };
-        case 'right':
-            return {
-                ...baseTooltipVariants,
-                initial: { ...baseTooltipVariants.initial, x: -2 },
-                animate: { ...baseTooltipVariants.animate, x: 0 },
-                exit: { ...baseTooltipVariants.exit, x: -2 }
-            };
-        case 'bottom':
-            return {
-                ...baseTooltipVariants,
-                initial: { ...baseTooltipVariants.initial, y: -2 },
-                animate: { ...baseTooltipVariants.animate, y: 0 },
-                exit: { ...baseTooltipVariants.exit, y: -2 }
-            };
-        case 'left':
-            return {
-                ...baseTooltipVariants,
-                initial: { ...baseTooltipVariants.initial, x: 2 },
-                animate: { ...baseTooltipVariants.animate, x: 0 },
-                exit: { ...baseTooltipVariants.exit, x: 2 }
-            };
-        default:
-            return baseTooltipVariants;
-    }
+    const side = placement.split('-')[0];
+    return getOverlayMenuVariants(side, {
+        scale: 0.98,
+        shift: 4,
+    });
 };
 /**
  * Spring animation configuration options
@@ -69,7 +31,11 @@ const tooltipSpringConfig = {
         stiffness: 200,
         damping: 25
     },
-    medium: springConfig,
+    medium: {
+        type: "spring",
+        stiffness: 380,
+        damping: 35
+    },
     bouncy: {
         type: "spring",
         stiffness: 400,

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

@@ -1,6 +1,6 @@
 import { TooltipProps } from "./Tooltip.types";
 declare const Tooltip: {
-    ({ content, children, placement, delay, disabled, className, maxWidth, minWidth, showOnFocus, wrapText, id, theme: themeOverrides, "aria-label": ariaLabel, role, offset, darkMode, }: TooltipProps): import("react/jsx-runtime").JSX.Element;
+    ({ content, children, placement, delay, disabled, className, triggerClassName, maxWidth, minWidth, showOnFocus, wrapText, id, theme: themeOverrides, "aria-label": ariaLabel, role, offset, darkMode, elevation, lift, isOpen, defaultIsOpen, onOpenChange, recalcTrigger, }: TooltipProps): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 };
 export { Tooltip };

package/dist/components/core/Tooltip/Tooltip.js

@@ -1,5 +1,6 @@
+"use client";
 import { jsx, jsxs } from 'react/jsx-runtime';
-import { useState, useRef, useCallback, useEffect } from 'react';
+import React__default, { useId, useState, useCallback, useRef, useEffect } from 'react';
 import { useReducedMotion, AnimatePresence, motion } from 'motion/react';
 import { createPortal } from 'react-dom';
 import { cn } from '../../../utils/cn.js';
@@ -7,38 +8,26 @@ import { tooltipTheme } from './Tooltip.theme.js';
 import { getTooltipVariants } from './Tooltip.animations.js';
 import { useSelectPortal } from '../../../hooks/useSelectPortal.js';
 import { useIsClient } from '../../../hooks/useIsClient.js';
+import { useDarkMode } from '../../../hooks/useDarkMode.js';
+import { useSurfaceElevation, SurfaceProvider, surfaceClasses } from '../../../theme/SurfaceContext.js';
 
-/**
- * Hook to detect dark mode state from document
- */
-const useDarkMode = () => {
-    const [isDark, setIsDark] = useState(false);
-    useEffect(() => {
-        if (typeof document === "undefined")
-            return;
-        const checkDarkMode = () => {
-            const hasDarkClass = document.documentElement.classList.contains("dark") ||
-                document.body.classList.contains("dark") ||
-                document.querySelector(".dark") !== null;
-            setIsDark(hasDarkClass);
-        };
-        checkDarkMode();
-        // Observe class changes on html and body
-        const observer = new MutationObserver(checkDarkMode);
-        observer.observe(document.documentElement, {
-            attributes: true,
-            attributeFilter: ["class"],
-        });
-        observer.observe(document.body, {
-            attributes: true,
-            attributeFilter: ["class"],
-        });
-        return () => observer.disconnect();
-    }, []);
-    return isDark;
-};
-const Tooltip = ({ content, children, placement = "top", delay = 300, disabled = false, className, maxWidth = "360px", minWidth = "fit-content", showOnFocus = true, wrapText = false, id, theme: themeOverrides, "aria-label": ariaLabel, role = "tooltip", offset = 8, darkMode = false, }) => {
-    const [isVisible, setIsVisible] = useState(false);
+const Tooltip = ({ content, children, placement = "top", delay = 300, disabled = false, className, triggerClassName, maxWidth = "360px", minWidth = "fit-content", showOnFocus = true, wrapText = false, id, theme: themeOverrides, "aria-label": ariaLabel, role = "tooltip", offset = 8, darkMode = false, elevation, lift, isOpen, defaultIsOpen = false, onOpenChange, recalcTrigger, }) => {
+    // Relative elevation: lift above the host surface (overlay base = 5).
+    const surfaceLevel = useSurfaceElevation({ baseRung: 5, offset: 2, elevation, lift });
+    // Stable id for the aria-describedby linkage — auto-generated via useId()
+    // (CLAUDE.md §9: IDs from useId(), never Math.random()) so the tooltip
+    // content is always programmatically associated with its trigger, even
+    // when the consumer doesn't pass an explicit `id`.
+    const generatedId = useId();
+    const tooltipId = id || `tooltip-${generatedId}`;
+    const isControlled = isOpen !== undefined;
+    const [internalVisible, setInternalVisible] = useState(defaultIsOpen);
+    const isVisible = isControlled ? isOpen : internalVisible;
+    const setVisible = useCallback((next) => {
+        if (!isControlled)
+            setInternalVisible(next);
+        onOpenChange === null || onOpenChange === void 0 ? void 0 : onOpenChange(next);
+    }, [isControlled, onOpenChange]);
     const tooltipRef = useRef(null);
     const triggerRef = useRef(null);
     const timerRef = useRef(null);
@@ -55,28 +44,45 @@ const Tooltip = ({ content, children, placement = "top", delay = 300, disabled =
     const { position, cssVariables, contentRef: portalContentRef} = useSelectPortal({
         triggerRef,
         isOpen: isVisible,
-        placement: placement, // TooltipPlacement matches SelectPlacement subset
+        placement: placement,
         offset,
         autoWidth: true,
+        recalcTrigger,
     });
-    // Event handlers - simplified timer management
+    // Dev warning (§9): controlled + uncontrolled props together — controlled wins.
+    useEffect(() => {
+        if (process.env.NODE_ENV !== "production") {
+            if (isControlled && defaultIsOpen) {
+                console.warn("[Tooltip]: Both `isOpen` and `defaultIsOpen` provided. Tooltip is controlled — `defaultIsOpen` is ignored.");
+            }
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    // Event handlers - simplified timer management.
+    // In controlled mode visibility is driven ENTIRELY by `isOpen` (see
+    // Tooltip.types.ts) — hover/focus/Escape must not fight the consumer's
+    // state, so both handlers bail. (`isOpen` without `onOpenChange` is a
+    // first-class display-only pattern — e.g. Slider's drag bubble — so no
+    // missing-handler warning here, unlike form controls.)
     const handleShowTooltip = useCallback(() => {
-        if (disabled)
+        if (disabled || isControlled)
             return;
         if (timerRef.current) {
             clearTimeout(timerRef.current);
         }
         timerRef.current = setTimeout(() => {
-            setIsVisible(true);
+            setVisible(true);
         }, delay);
-    }, [disabled, delay]);
+    }, [disabled, isControlled, delay, setVisible]);
     const handleHideTooltip = useCallback(() => {
+        if (isControlled)
+            return;
         if (timerRef.current) {
             clearTimeout(timerRef.current);
         }
         // Immediate hide for better responsiveness
-        setIsVisible(false);
-    }, []);
+        setVisible(false);
+    }, [isControlled, setVisible]);
     // Clean up timeout on unmount
     useEffect(() => {
         return () => {
@@ -91,11 +97,14 @@ const Tooltip = ({ content, children, placement = "top", delay = 300, disabled =
             handleHideTooltip();
         }
     }, [handleHideTooltip]);
-    // Event handlers for trigger element
+    // Determine whether the child can receive focus events via cloneElement.
+    // If so, focus/blur are forwarded to the child; otherwise fall back to the wrapper.
+    const childCanReceiveFocus = showOnFocus && React__default.isValidElement(children);
+    // Event handlers for the wrapper div (focus/blur only go here as fallback)
     const triggerHandlers = {
         onMouseEnter: handleShowTooltip,
         onMouseLeave: handleHideTooltip,
-        ...(showOnFocus && {
+        ...(showOnFocus && !childCanReceiveFocus && {
             onFocus: handleShowTooltip,
             onBlur: handleHideTooltip,
         }),
@@ -115,16 +124,51 @@ const Tooltip = ({ content, children, placement = "top", delay = 300, disabled =
         ? ""
         : "text-ellipsis overflow-hidden whitespace-nowrap";
     const widthClasses = cn(minWidth === "fit-content" ? "w-fit" : "min-w-fit", textOverflowClass);
-    const tooltipContent = (jsx(AnimatePresence, { children: isVisible && (jsx(motion.div, { id: id, role: role, ref: handleRef, style: {
+    const tooltipContent = (jsx(AnimatePresence, { children: isVisible && (jsx(motion.div, { id: tooltipId, role: role, ref: handleRef, style: {
                 maxWidth,
                 minWidth: minWidth !== "fit-content" ? minWidth : undefined,
                 width: "max-content",
                 ...cssVariables,
                 top: `${position.top}px`,
                 left: `${position.left}px`,
-            }, className: cn(theme.baseStyle, widthClasses, className), "aria-hidden": !isVisible, "aria-label": ariaLabel, "aria-live": role === "tooltip" ? "polite" : undefined, variants: shouldReduceMotion ? {} : getTooltipVariants(placement), initial: shouldReduceMotion ? undefined : "initial", animate: shouldReduceMotion ? undefined : "animate", exit: shouldReduceMotion ? undefined : "exit", children: content })) }));
-    return (jsxs("div", { className: "relative inline-block", ref: triggerRef, ...triggerHandlers, tabIndex: showOnFocus ? 0 : undefined, "aria-describedby": isVisible && id ? id : undefined, children: [children, isClient &&
-                createPortal(jsx("div", { className: darkMode || isDarkMode ? "dark" : undefined, children: tooltipContent }), document.body)] }));
+            }, className: cn(surfaceClasses(surfaceLevel, { translucent: true, shadow: false }), theme.baseStyle, widthClasses, className), "aria-hidden": !isVisible, "aria-label": ariaLabel, variants: shouldReduceMotion ? {} : getTooltipVariants(placement), initial: shouldReduceMotion ? undefined : "initial", animate: shouldReduceMotion ? undefined : "animate", exit: shouldReduceMotion ? undefined : "exit", children: jsx(SurfaceProvider, { level: surfaceLevel, children: content }) })) }));
+    // The tooltip content must be associated with the actual INTERACTIVE
+    // trigger element (e.g. the button being wrapped), not the non-interactive
+    // wrapper div — assistive tech resolves aria-describedby from the
+    // focused/interactive element, so an ancestor div carrying the attribute
+    // has no effect. When the child is a cloneable element, forward both
+    // focus/blur (as before, gated on showOnFocus) and aria-describedby
+    // directly onto it; only fall back to the wrapper when `children` isn't a
+    // valid element to clone (e.g. plain text) and there is no other place to
+    // put the attribute.
+    const isElementChild = React__default.isValidElement(children);
+    // Merge with any aria-describedby the child already carries (e.g. a form
+    // control describing itself via its own helper/error text) instead of
+    // clobbering it — ARIA allows a space-separated list of ids.
+    const existingDescribedBy = isElementChild
+        ? children.props["aria-describedby"]
+        : undefined;
+    const mergedDescribedBy = [existingDescribedBy, isVisible ? tooltipId : undefined].filter(Boolean).join(" ") ||
+        undefined;
+    const childWithFocusHandlers = isElementChild
+        ? React__default.cloneElement(children, {
+            ...(childCanReceiveFocus && {
+                onFocus: (e) => {
+                    var _a, _b;
+                    handleShowTooltip();
+                    (_b = (_a = children.props).onFocus) === null || _b === void 0 ? void 0 : _b.call(_a, e);
+                },
+                onBlur: (e) => {
+                    var _a, _b;
+                    handleHideTooltip();
+                    (_b = (_a = children.props).onBlur) === null || _b === void 0 ? void 0 : _b.call(_a, e);
+                },
+            }),
+            "aria-describedby": mergedDescribedBy,
+        })
+        : children;
+    return (jsxs("div", { className: cn("relative inline-block", triggerClassName), ref: triggerRef, ...triggerHandlers, "aria-describedby": !isElementChild && isVisible ? tooltipId : undefined, children: [childWithFocusHandlers, isClient &&
+                createPortal(jsx("div", { "data-flikkui-portal": "", className: darkMode || isDarkMode ? "dark" : undefined, children: tooltipContent }), document.body)] }));
 };
 // Set display name for dev tools and Storybook
 Tooltip.displayName = "Tooltip";

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

@@ -1,7 +1,8 @@
 const tooltipTheme = {
-    // Base style for the tooltip - using fixed positioning for portal rendering
-    baseStyle: "fixed z-[99] rounded-[var(--tooltip-radius)] py-1 px-2 text-xs text-[var(--color-text-primary)] focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)] focus-visible:ring-offset-2 pointer-events-none bg-white/60 backdrop-blur-md outline outline-[var(--color-border)] shadow-lg border-t-[1px] border-white " +
-        "dark:bg-neutral-800/80 dark:outline-[var(--color-border)]/80 dark:border-[var(--color-border)]",
+    // Base style for the tooltip - using fixed positioning for portal rendering.
+    // bg comes from the relative-elevation engine (surfaceClasses) at runtime so a
+    // tooltip lifts above its host; keep the frosted blur + outline + shadow here.
+    baseStyle: "fixed z-[99] rounded-[var(--tooltip-radius)] py-1 px-2 text-xs text-[var(--color-text-primary)] focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)] focus-visible:ring-offset-2 pointer-events-none backdrop-blur-lg outline outline-[var(--color-border)] shadow-lg",
 };
 
 export { tooltipTheme };

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

@@ -1,4 +1,5 @@
 import { ReactNode } from "react";
+import type { SurfaceElevation } from "../../../theme/SurfaceContext";
 export type TooltipPlacement = "top" | "right" | "bottom" | "left";
 export interface TooltipThemeOverrides {
     /**
@@ -38,9 +39,13 @@ export interface TooltipProps {
      */
     disabled?: boolean;
     /**
-     * Additional classes for the tooltip container
+     * Additional classes for the tooltip container (the tooltip bubble)
      */
     className?: string;
+    /**
+     * Additional classes for the trigger wrapper element
+     */
+    triggerClassName?: string;
     /**
      * Max width for the tooltip content
      * @default "360px"
@@ -95,4 +100,36 @@ export interface TooltipProps {
      * @default false
      */
     darkMode?: boolean;
+    /**
+     * Pin the surface elevation rung (overrides the automatic relative lift).
+     * A rung number (1–8) or a semantic alias ("surface"/"raised"/"overlay"…).
+     */
+    elevation?: SurfaceElevation;
+    /** `false` opts out of the relative lift — paints at the tooltip's base rung. */
+    lift?: boolean;
+    /**
+     * Controlled visibility — when provided, visibility is driven entirely by
+     * this prop instead of internal hover/focus state (delay is bypassed).
+     * Use for triggers whose "show tooltip" moment isn't a plain hover, e.g. a
+     * value bubble shown only while dragging a Slider thumb.
+     */
+    isOpen?: boolean;
+    /**
+     * Initial visibility for uncontrolled usage.
+     * @default false
+     */
+    defaultIsOpen?: boolean;
+    /**
+     * Called when internal hover/focus logic changes visibility (uncontrolled
+     * mode). In controlled mode visibility is owned by `isOpen` and the
+     * internal triggers are bypassed entirely, so this never fires — update
+     * your own state instead.
+     */
+    onOpenChange?: (isOpen: boolean) => void;
+    /**
+     * Opt-in escape hatch for triggers that move on their own (e.g. a dragged
+     * slider thumb) without a scroll/resize/content-resize event to key off
+     * of. Position recalculates whenever this value changes.
+     */
+    recalcTrigger?: unknown;
 }

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

@@ -1,6 +1,5 @@
-import { Variants, Transition } from 'motion/react';
+import { Variants } from 'motion/react';
 export declare const treeNodeVariants: Variants;
 export declare const expandIconVariants: Variants;
-export declare const childrenStagger: Transition;
 export declare const childNodeVariants: Variants;
 export declare const getReducedMotionVariants: (originalVariants: Variants) => Variants;

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

@@ -1,51 +1,15 @@
-// Optimized spring configuration for smooth expand/collapse
-const SPRING_CONFIG = {
-    type: 'spring',
-    stiffness: 400,
-    damping: 30,
-    mass: 0.8,
-};
-// Core expand/collapse animation for tree nodes
-const treeNodeVariants = {
-    expanded: {
-        opacity: 1,
-        scaleY: 1,
-        height: 'auto',
-        transition: {
-            height: {
-                ...SPRING_CONFIG,
-                duration: 0.3,
-            },
-            opacity: {
-                ...SPRING_CONFIG,
-                duration: 0.2,
-            },
-            scaleY: {
-                ...SPRING_CONFIG,
-                duration: 0.25,
-            },
-        },
-    },
-    collapsed: {
-        opacity: 0,
-        scaleY: 0.8,
-        height: 0,
-        transition: {
-            height: {
-                ...SPRING_CONFIG,
-                duration: 0.25,
-            },
-            opacity: {
-                ...SPRING_CONFIG,
-                duration: 0.15,
-            },
-            scaleY: {
-                ...SPRING_CONFIG,
-                duration: 0.2,
-            },
-        },
-    },
-};
+"use client";
+import '../../../theme/ThemeContext.js';
+import '../../../theme/SurfaceContext.js';
+import { getExpandCollapseVariants, springs } from '../../../theme/animations.js';
+
+// Use centralized smooth spring preset
+const SPRING_CONFIG = springs.smooth;
+// Core expand/collapse animation for the children container.
+const treeNodeVariants = getExpandCollapseVariants({
+    staggerChildren: 0.03,
+    delayChildren: 0.03,
+});
 // Icon rotation animation for expand/collapse indication
 const expandIconVariants = {
     expanded: {
@@ -57,21 +21,19 @@ const expandIconVariants = {
         transition: SPRING_CONFIG,
     },
 };
-// Stagger animation for children nodes
-const childrenStagger = {
-    staggerChildren: 0.03,
-    delayChildren: 0.05,
-};
-// Individual child node entry animation
+// Individual child node entry animation.
+// Fades in and slides diagonally (down and right) for an organic vertical flow.
 const childNodeVariants = {
-    hidden: {
+    collapsed: {
         opacity: 0,
-        x: -10,
+        x: -4,
+        y: -4,
         transition: SPRING_CONFIG,
     },
-    visible: {
+    expanded: {
         opacity: 1,
         x: 0,
+        y: 0,
         transition: SPRING_CONFIG,
     },
 };
@@ -93,4 +55,4 @@ const getReducedMotionVariants = (originalVariants) => {
     return reducedVariants;
 };
 
-export { childNodeVariants, childrenStagger, expandIconVariants, getReducedMotionVariants, treeNodeVariants };
+export { childNodeVariants, expandIconVariants, getReducedMotionVariants, treeNodeVariants };