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

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

@@ -4,7 +4,7 @@ const tagTheme = {
         "text-[var(--color-text-primary)]",
     sizes: {
         sm: "text-xs px-2 py-0.5",
-        md: "text-sm 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-*`.
@@ -20,7 +20,7 @@ const tagTheme = {
         md: "",
     },
     disabledStyle: "opacity-50 cursor-not-allowed",
-    removeButtonStyle: "inline-flex items-center justify-center rounded-full p-1 " +
+    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 " +

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;

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

@@ -1,33 +1,36 @@
+import '../../../theme/ThemeContext.js';
+import '../../../theme/SurfaceContext.js';
+import { springs } from '../../../theme/animations.js';
+
 const toastAnimations = {
-    // Initial state when toast appears
+    // Initial state when toast appears (subtle slide up + scale in)
     initial: {
         opacity: 0,
-        y: 50,
-        scale: 0.3,
+        y: 24,
+        scale: 0.94,
     },
-    // Exit animation when toast is dismissed
+    // Exit animation when toast is dismissed (quick fade out + scale down)
     exit: {
         opacity: 0,
-        scale: 0.5,
-        transition: { duration: 0.2 },
-    },
-    // Spring transition configuration
-    transition: {
-        type: "spring",
-        stiffness: 500,
-        damping: 30,
-        mass: 1,
+        scale: 0.94,
+        transition: { duration: 0.15, ease: "easeIn" },
     },
+    // Premium spring transition configuration
+    transition: springs.premium,
 };
 // Stacking animation utilities
-const getToastStackingAnimation = (index, totalToasts, isExpanded, expandedY) => {
+const getToastStackingAnimation = (index, totalToasts, isExpanded, expandedY, position) => {
+    var _a;
     if (totalToasts === 1)
         return {};
+    const isBottom = (_a = position === null || position === void 0 ? void 0 : position.startsWith("bottom")) !== null && _a !== void 0 ? _a : false;
+    const directionMultiplier = isBottom ? -1 : 1;
     const maxVisible = 3; // Show max 3 toasts in stack
     const stackIndex = Math.min(index, maxVisible - 1);
     if (isExpanded) {
+        const yVal = expandedY !== undefined ? expandedY * directionMultiplier : index * 80 * directionMultiplier;
         return {
-            y: expandedY !== null && expandedY !== void 0 ? expandedY : index * 80,
+            y: yVal,
             scale: 1,
             zIndex: totalToasts - index,
             opacity: 1,
@@ -37,14 +40,14 @@ const getToastStackingAnimation = (index, totalToasts, isExpanded, expandedY) =>
         // Stacked state - compress toasts
         if (index >= maxVisible) {
             return {
-                y: (maxVisible - 1) * 10,
+                y: (maxVisible - 1) * 10 * directionMultiplier,
                 scale: 1 - (maxVisible - 1) * 0.08,
                 zIndex: 0,
                 opacity: 0.3,
             };
         }
         return {
-            y: stackIndex * 10,
+            y: stackIndex * 10 * directionMultiplier,
             scale: 1 - stackIndex * 0.08,
             zIndex: totalToasts - index,
             opacity: 1 - stackIndex * 0.25,

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

@@ -1,18 +1,22 @@
+"use client";
 import { jsx, jsxs } from 'react/jsx-runtime';
 import React__default, { useRef, useCallback, useEffect, useMemo } from 'react';
 import { useReducedMotion, motion } from 'motion/react';
 import { cn } from '../../../utils/cn.js';
+import { useSurfaceElevation, SurfaceProvider, surfaceClasses } from '../../../theme/SurfaceContext.js';
 import { toastTheme } from './Toast.theme.js';
-import { toastAnimations, getToastStackingAnimation } from './Toast.animations.js';
+import { getToastStackingAnimation, toastAnimations } from './Toast.animations.js';
 import { ArrowPathIcon, InformationCircleIcon, XMarkIcon } from '@heroicons/react/24/solid';
-import { Button } from '../Button/Button.js';
+import { Link } from '../Link/Link.js';
 
 const isToastAction = (action) => typeof action === "object" &&
     action !== null &&
     "label" in action &&
     "onClick" in action;
-const Toast = React__default.forwardRef(({ toast, className, onDismiss, index = 0, isExpanded = false, totalToasts = 1, onMouseEnter, onMouseLeave, onHeightChange, expandedOffset, darkMode = false, ...props }, ref) => {
-    var _a;
+const Toast = React__default.forwardRef(({ toast, className, onDismiss, index = 0, isExpanded = false, totalToasts = 1, onMouseEnter, onMouseLeave, onHeightChange, expandedOffset, darkMode = false, elevation, lift, position, ...props }, ref) => {
+    // Grounded overlay: a toast portals to a page-level toaster, so it paints a FIXED rung 5
+    // (a punchy overlay shade) rather than inheriting whatever surface its trigger sat in.
+    const surfaceLevel = useSurfaceElevation({ baseRung: 5, ground: true, elevation, lift });
     const internalRef = useRef(null);
     const setRefs = useCallback((node) => {
         internalRef.current = node;
@@ -24,19 +28,38 @@ const Toast = React__default.forwardRef(({ toast, className, onDismiss, index =
         }
     }, [ref]);
     const shouldReduceMotion = useReducedMotion();
-    const { id, variant = "default", state = "default", title, subtitle, icon, action, children, duration = 5000, dismissible = true, } = toast;
+    const { id, state = "default", color, title, subtitle, icon, action, children, duration = 5000, dismissible = true, } = toast;
     const isTextOnly = !subtitle && !action && !children;
+    // Per-toast live-region role, driven by severity: `danger`/`warning` are
+    // urgent (role="alert" ~ implicit aria-live="assertive"), everything else
+    // is a routine update (role="status" ~ implicit aria-live="polite"). The
+    // shared toaster container (ToastProvider) keeps its own
+    // `aria-live="polite"` and does NOT get a role — the two announcement
+    // mechanisms would otherwise double up. Instead, each toast is inserted
+    // as a fully-formed subtree (role included at mount, not added after),
+    // so assistive tech announces it exactly once, using this more specific
+    // role/urgency rather than the container's generic "polite" default.
+    const toastRole = color === "danger" || color === "warning" ? "alert" : "status";
     const defaultIcon = state === "loading" ? (jsx(motion.div, { animate: { rotate: 360 }, transition: { repeat: Infinity, duration: 1, ease: "linear" }, children: jsx(ArrowPathIcon, { className: "w-5 h-5" }) })) : (jsx(InformationCircleIcon, { className: "w-5 h-5" }));
     const resolvedIcon = icon || defaultIcon;
-    // Auto-dismiss after duration
+    // Auto-dismiss after duration (pauses when hovered/expanded, then RESUMES the remaining
+    // time rather than restarting the full countdown — otherwise intermittent hover keeps
+    // resetting the timer and the toast never dismisses).
+    const remainingRef = useRef(duration);
     useEffect(() => {
-        if (duration > 0 && dismissible) {
-            const timer = setTimeout(() => {
-                onDismiss === null || onDismiss === void 0 ? void 0 : onDismiss(id);
-            }, duration);
-            return () => clearTimeout(timer);
-        }
-    }, [duration, dismissible, id, onDismiss]);
+        remainingRef.current = duration;
+    }, [duration]);
+    useEffect(() => {
+        if (!(duration > 0 && dismissible) || isExpanded)
+            return;
+        const start = Date.now();
+        const remaining = remainingRef.current;
+        const timer = setTimeout(() => onDismiss === null || onDismiss === void 0 ? void 0 : onDismiss(id), remaining);
+        return () => {
+            clearTimeout(timer);
+            remainingRef.current = Math.max(0, remaining - (Date.now() - start));
+        };
+    }, [duration, dismissible, id, onDismiss, isExpanded]);
     // Report measured height to parent
     useEffect(() => {
         if (internalRef.current && onHeightChange) {
@@ -55,7 +78,7 @@ const Toast = React__default.forwardRef(({ toast, className, onDismiss, index =
             }
         }
     };
-    const stackingStyle = getToastStackingAnimation(index, totalToasts, isExpanded, expandedOffset);
+    const stackingStyle = getToastStackingAnimation(index, totalToasts, isExpanded, expandedOffset, position);
     const animateValue = useMemo(() => {
         var _a, _b, _c, _d;
         return ({
@@ -77,16 +100,15 @@ const Toast = React__default.forwardRef(({ toast, className, onDismiss, index =
             position: (index > 0
                 ? "absolute"
                 : "relative"),
-            top: index > 0 ? 0 : undefined,
+            top: index > 0 && !(position === null || position === void 0 ? void 0 : position.startsWith("bottom")) ? 0 : undefined,
+            bottom: index > 0 && (position === null || position === void 0 ? void 0 : position.startsWith("bottom")) ? 0 : undefined,
             left: index > 0 ? 0 : undefined,
             width: index > 0 ? "100%" : undefined,
         });
-    }, [stackingStyle.zIndex, index]);
-    const toastNode = (jsxs(motion.div, { ref: setRefs, layout: true, initial: shouldReduceMotion ? false : toastAnimations.initial, animate: animateValue, exit: shouldReduceMotion
+    }, [stackingStyle.zIndex, index, position]);
+    const toastNode = (jsx(motion.div, { ref: setRefs, role: toastRole, layout: true, initial: shouldReduceMotion ? false : toastAnimations.initial, animate: animateValue, exit: shouldReduceMotion
             ? { ...toastAnimations.exit, transition: { duration: 0 } }
-            : toastAnimations.exit, transition: shouldReduceMotion ? { duration: 0 } : toastAnimations.transition, className: cn(toastTheme.baseStyle, isTextOnly && "items-center", ((_a = toastTheme.variants) === null || _a === void 0 ? void 0 : _a[variant]) || "", "pointer-events-auto", index > 0 && !isExpanded && "absolute top-0 left-0", className), style: styleValue, role: "status", "aria-live": "polite", children: [jsx("div", { className: cn(toastTheme.iconStyle, !isTextOnly && "mt-0.5"), children: resolvedIcon }), jsxs("div", { className: "flex-1 min-w-0", children: [title &&
-                        (typeof title === "string" ? (jsx("div", { className: cn(toastTheme.titleStyle, !isTextOnly && "font-semibold"), children: title })) : (title)), subtitle &&
-                        (typeof subtitle === "string" ? (jsx("div", { className: toastTheme.subtitleStyle, children: subtitle })) : (subtitle)), action && (jsx("div", { className: "mt-4", children: isToastAction(action) ? (jsx(Button, { variant: "link", color: "primary", onClick: handleActionClick, children: action.label })) : (action) })), children] }), dismissible && (jsx("button", { type: "button", className: cn(toastTheme.closeButtonStyle, !isTextOnly && "mt-0.5"), onClick: handleDismiss, "aria-label": "Dismiss notification", children: jsx(XMarkIcon, { className: "size-5" }) }))] }));
+            : toastAnimations.exit, transition: shouldReduceMotion ? { duration: 0 } : toastAnimations.transition, className: cn(surfaceClasses(surfaceLevel, { translucent: true, shadow: true }), toastTheme.baseStyle, isTextOnly && "items-center", "pointer-events-auto", index > 0 && !isExpanded && "absolute top-0 left-0", className), style: styleValue, children: jsxs(SurfaceProvider, { level: surfaceLevel, children: [jsx("div", { className: cn(toastTheme.iconStyle, !isTextOnly && "mt-0.5"), children: resolvedIcon }), jsxs("div", { className: "flex-1 min-w-0", children: [title && jsx("div", { className: toastTheme.titleStyle, children: title }), subtitle && (jsx("div", { className: toastTheme.subtitleStyle, children: subtitle })), action && (jsx("div", { className: "mt-4", children: isToastAction(action) ? (jsx(Link, { color: "primary", size: "sm", onClick: handleActionClick, children: action.label })) : (action) })), children] }), dismissible && (jsx("button", { type: "button", className: cn(toastTheme.closeButtonStyle, !isTextOnly && "mt-0.5"), onClick: handleDismiss, "aria-label": "Dismiss notification", children: jsx(XMarkIcon, { className: "size-5" }) }))] }) }));
     if (darkMode) {
         return jsx("div", { className: "dark", children: toastNode });
     }

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

@@ -1,13 +1,10 @@
 const toastTheme = {
-    baseStyle: "flex items-start gap-3 rounded-[var(--toast-radius)] px-4 py-3 shadow-2xl backdrop-blur-sm w-full ring-[0.5px] ring-white dark:ring-white/10 dark:shadow-black/40 " +
-        "bg-white/80 text-[var(--color-text-primary)] " +
-        "dark:bg-[var(--color-background-secondary)]/60",
-    variants: {
-        default: "border border-[var(--color-border)] dark:border-white/10",
-        glass: "glass-effect",
-    },
+    // bg + drop shadow come from the relative-elevation engine (surfaceClasses) at runtime;
+    // keep the frosted blur + ring + border + radius here.
+    baseStyle: "flex items-start gap-3 rounded-[var(--toast-radius)] px-4 py-3 backdrop-blur-sm w-full ring-[0.5px] ring-white dark:ring-white/10 " +
+        "text-[var(--color-text-primary)] border border-[var(--color-border)]",
     iconStyle: "flex-shrink-0",
-    titleStyle: "text-sm text-[var(--color-text-primary)]",
+    titleStyle: "text-sm text-[var(--color-text-primary)] font-semibold",
     subtitleStyle: "text-sm mt-1 text-[var(--color-text-secondary)]",
     closeButtonStyle: "flex-shrink-0 size-5 opacity-70 hover:opacity-100 transition-opacity cursor-pointer",
     containerStyle: "fixed z-50 pointer-events-none",

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

@@ -1,8 +1,6 @@
 import { HTMLAttributes, ReactNode } from "react";
-/**
- * Toast visual variant
- */
-export type ToastVariant = "default" | "glass";
+import type { SurfaceElevation } from "../../../theme/SurfaceContext";
+import type { SemanticColor } from "../../../utils/colorUtils";
 /**
  * Toast state (e.g., loading indicator)
  */
@@ -14,7 +12,6 @@ export interface ToastAction {
 }
 export interface ToastTheme {
     baseStyle: string;
-    variants: Record<ToastVariant, string>;
     iconStyle: string;
     titleStyle: string;
     subtitleStyle: string;
@@ -23,8 +20,14 @@ export interface ToastTheme {
 }
 export interface ToastData {
     id: string;
-    variant?: ToastVariant;
     state?: ToastState;
+    /**
+     * Semantic severity of the toast. Drives the per-toast live-region role
+     * (`danger`/`warning` -> `role="alert"`, everything else -> `role="status"`)
+     * as well as `useToast()`'s convenience-method icon color.
+     * @default "neutral"
+     */
+    color?: SemanticColor;
     title?: ReactNode;
     subtitle?: ReactNode;
     icon?: ReactNode;
@@ -32,7 +35,6 @@ export interface ToastData {
     children?: ReactNode;
     duration?: number;
     dismissible?: boolean;
-    onDismiss?: () => void;
 }
 export interface ToastProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
     /** Toast data */
@@ -55,12 +57,21 @@ export interface ToastProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"
     onHeightChange?: (id: string, height: number) => void;
     /** Pre-calculated y-offset for expanded state */
     expandedOffset?: number;
+    /** Toast position */
+    position?: ToastPosition;
     /**
      * Enable dark mode styling. When true, applies the `dark` class so components
      * use light colors for visibility.
      * @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 toast's base rung. */
+    lift?: boolean;
 }
 export interface ToastProviderProps {
     children: ReactNode;
@@ -80,7 +91,6 @@ export interface ToastContextValue {
     removeAllToasts: () => void;
 }
 export interface UseToastOptions {
-    variant?: ToastVariant;
     state?: ToastState;
     duration?: number;
     dismissible?: boolean;
@@ -89,23 +99,23 @@ export interface UseToastOptions {
     icon?: ReactNode;
 }
 export interface UseToastReturn {
-    toast: (title: string, options?: UseToastOptions & {
-        subtitle?: string;
+    toast: (title: ReactNode, options?: UseToastOptions & {
+        subtitle?: ReactNode;
     }) => string;
-    success: (title: string, options?: UseToastOptions & {
-        subtitle?: string;
+    success: (title: ReactNode, options?: UseToastOptions & {
+        subtitle?: ReactNode;
     }) => string;
-    error: (title: string, options?: UseToastOptions & {
-        subtitle?: string;
+    error: (title: ReactNode, options?: UseToastOptions & {
+        subtitle?: ReactNode;
     }) => string;
-    warning: (title: string, options?: UseToastOptions & {
-        subtitle?: string;
+    warning: (title: ReactNode, options?: UseToastOptions & {
+        subtitle?: ReactNode;
     }) => string;
-    info: (title: string, options?: UseToastOptions & {
-        subtitle?: string;
+    info: (title: ReactNode, options?: UseToastOptions & {
+        subtitle?: ReactNode;
     }) => string;
-    loading: (title: string, options?: Omit<UseToastOptions, "state"> & {
-        subtitle?: string;
+    loading: (title: ReactNode, options?: Omit<UseToastOptions, "state"> & {
+        subtitle?: ReactNode;
     }) => string;
     dismiss: (id: string) => void;
     dismissAll: () => void;

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';
@@ -92,7 +93,10 @@ const ToastProvider = ({ children, position = 'top-right', maxToasts = 5, defaul
         removeAllToasts,
     }), [toasts, addToast, removeToast, removeAllToasts]);
     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: 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))) }) }) }), portalTarget) : 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, 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,3 +1,4 @@
+"use client";
 import React__default, { useCallback } from 'react';
 import { InformationCircleIcon, ExclamationTriangleIcon, XCircleIcon, CheckCircleIcon } from '@heroicons/react/24/solid';
 import { useToastContext } from './ToastProvider.js';
@@ -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,8 +24,8 @@ 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,
@@ -36,8 +36,8 @@ const useToast = () => {
     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,
@@ -48,8 +48,8 @@ const useToast = () => {
     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,
@@ -60,8 +60,8 @@ const useToast = () => {
     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,
@@ -73,7 +73,6 @@ const useToast = () => {
         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, triggerClassName, 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, }: 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 React__default, { useState, useRef, useCallback, useEffect } from 'react';
+import React__default, { useId, useState, useRef, useCallback, useEffect } from 'react';
 import { useReducedMotion, AnimatePresence, motion } from 'motion/react';
 import { createPortal } from 'react-dom';
 import { cn } from '../../../utils/cn.js';
@@ -8,8 +9,17 @@ 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';
 
-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, }) => {
+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, }) => {
+    // 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 [isVisible, setIsVisible] = useState(false);
     const tooltipRef = useRef(null);
     const triggerRef = useRef(null);
@@ -90,31 +100,42 @@ 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, variants: shouldReduceMotion ? {} : getTooltipVariants(placement), initial: shouldReduceMotion ? undefined : "initial", animate: shouldReduceMotion ? undefined : "animate", exit: shouldReduceMotion ? undefined : "exit", children: content })) }));
-    // When the child is a valid element, forward focus/blur events directly onto it
-    // instead of adding tabIndex to the wrapper (which would create a double Tab stop).
-    const childWithFocusHandlers = childCanReceiveFocus
+            }, 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);
+    const childWithFocusHandlers = isElementChild
         ? React__default.cloneElement(children, {
-            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);
-            },
+            ...(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": isVisible ? tooltipId : undefined,
         })
         : children;
-    return (jsxs("div", { className: cn("relative inline-block", triggerClassName), ref: triggerRef, ...triggerHandlers, "aria-describedby": isVisible && id ? id : undefined, children: [childWithFocusHandlers, isClient &&
+    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

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

@@ -1,6 +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-[var(--color-surface-overlay)]/80 backdrop-blur-lg outline outline-[var(--color-border)] shadow-lg",
+    // 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 };