@udixio/ui-react 2.9.8 → 2.9.10

package/src/lib/components/Tooltip.tsx

@@ -0,0 +1,217 @@
+import { cloneElement, isValidElement, useEffect, useRef } from 'react';
+import { MotionProps } from '../utils';
+import { Button } from './Button';
+import { ToolTipInterface } from '../interfaces';
+import { useToolTipStyle } from '../styles';
+import { AnimatePresence, motion } from 'motion/react';
+import { SyncedFixedWrapper } from '../effects';
+import { useTooltipTrigger, useTooltipPosition } from '../hooks';
+
+/**
+ * Tooltips display brief labels or messages
+ * @status beta
+ * @category Communication
+ * @devx
+ * - `content` overrides `title`/`text`/`buttons` for fully custom content.
+ * - Supports controlled `isOpen` plus `openDelay`/`closeDelay`.
+ * @a11y
+ * - Provides `role="tooltip"` and `aria-describedby` when open.
+ */
+export const Tooltip = ({
+  variant = 'plain',
+  buttons,
+  className,
+  children,
+  title,
+  text,
+  content,
+  position: positionProp,
+  targetRef,
+  ref,
+  trigger = ['hover', 'focus'],
+  transition,
+  openDelay = 400,
+  closeDelay = 150,
+  isOpen: isOpenProp,
+  defaultOpen = false,
+  onOpenChange,
+  id,
+  ...props
+}: MotionProps<ToolTipInterface>) => {
+  transition = { duration: 0.3, ...transition };
+
+  if (!children && !targetRef) {
+    throw new Error('Tooltip must have a child or a targetRef');
+  }
+
+  if (buttons && !Array.isArray(buttons)) {
+    buttons = [buttons];
+  }
+
+  const internalRef = useRef<HTMLElement | null>(null);
+  const resolvedRef = targetRef || internalRef;
+
+  // Use the trigger hook for state management and accessibility
+  const { triggerProps, tooltipProps, isOpen } = useTooltipTrigger({
+    trigger,
+    isOpen: isOpenProp,
+    defaultOpen,
+    onOpenChange,
+    openDelay,
+    closeDelay,
+    id,
+  });
+
+  // Use the position hook for auto-positioning
+  const { resolvedPosition } = useTooltipPosition({
+    targetRef: resolvedRef,
+    position: positionProp,
+    variant,
+    isOpen,
+  });
+
+  // Apply trigger props to the target element
+  const enhancedChildren =
+    !targetRef && isValidElement(children)
+      ? cloneElement(children, {
+          ref: internalRef,
+          ...triggerProps,
+          // Merge event handlers if the child already has them
+          onMouseEnter: (e: React.MouseEvent) => {
+            triggerProps.onMouseEnter();
+            (children.props as any)?.onMouseEnter?.(e);
+          },
+          onMouseLeave: (e: React.MouseEvent) => {
+            triggerProps.onMouseLeave();
+            (children.props as any)?.onMouseLeave?.(e);
+          },
+          onFocus: (e: React.FocusEvent) => {
+            triggerProps.onFocus();
+            (children.props as any)?.onFocus?.(e);
+          },
+          onBlur: (e: React.FocusEvent) => {
+            triggerProps.onBlur();
+            (children.props as any)?.onBlur?.(e);
+          },
+          onClick: (e: React.MouseEvent) => {
+            triggerProps.onClick();
+            (children.props as any)?.onClick?.(e);
+          },
+          onKeyDown: (e: React.KeyboardEvent) => {
+            triggerProps.onKeyDown(e);
+            (children.props as any)?.onKeyDown?.(e);
+          },
+        } as any)
+      : children;
+
+  // Attach trigger handlers when using targetRef (no direct child to clone)
+  useEffect(() => {
+    if (!targetRef) return;
+    const element = targetRef.current;
+    if (!element) return;
+
+    const handleMouseEnter = () => triggerProps.onMouseEnter();
+    const handleMouseLeave = () => triggerProps.onMouseLeave();
+    const handleFocus = () => triggerProps.onFocus();
+    const handleBlur = () => triggerProps.onBlur();
+    const handleClick = () => triggerProps.onClick();
+    const handleKeyDown = (event: KeyboardEvent) =>
+      triggerProps.onKeyDown(event as unknown as React.KeyboardEvent);
+
+    element.addEventListener('mouseenter', handleMouseEnter);
+    element.addEventListener('mouseleave', handleMouseLeave);
+    element.addEventListener('focus', handleFocus, true);
+    element.addEventListener('blur', handleBlur, true);
+    element.addEventListener('click', handleClick);
+    element.addEventListener('keydown', handleKeyDown);
+
+    if (triggerProps['aria-describedby']) {
+      element.setAttribute(
+        'aria-describedby',
+        triggerProps['aria-describedby'],
+      );
+    } else {
+      element.removeAttribute('aria-describedby');
+    }
+
+    return () => {
+      element.removeEventListener('mouseenter', handleMouseEnter);
+      element.removeEventListener('mouseleave', handleMouseLeave);
+      element.removeEventListener('focus', handleFocus, true);
+      element.removeEventListener('blur', handleBlur, true);
+      element.removeEventListener('click', handleClick);
+      element.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [targetRef, triggerProps]);
+
+  const styles = useToolTipStyle({
+    variant,
+    buttons,
+    className,
+    title,
+    text,
+    position: resolvedPosition,
+    trigger,
+    targetRef: targetRef as any,
+    children: children as any,
+  });
+
+  const variants = {
+    open: {
+      opacity: 1,
+      height: 'auto',
+    },
+    close: {
+      opacity: 0,
+      height: 16,
+    },
+  };
+
+  return (
+    <>
+      {enhancedChildren}
+      <AnimatePresence>
+        {isOpen && (
+          <SyncedFixedWrapper targetRef={resolvedRef}>
+            <motion.div
+              initial={'close'}
+              variants={variants}
+              animate={'open'}
+              transition={{ duration: transition.duration }}
+              exit={'close'}
+              className={styles.toolTip}
+              {...props}
+              {...tooltipProps}
+            >
+              <div className={styles.container}>
+                {content ? (
+                  <div className={styles.content}>{content}</div>
+                ) : (
+                  <>
+                    {title && <div className={styles.subHead}>{title}</div>}
+                    {text && (
+                      <div className={styles.supportingText}>{text}</div>
+                    )}
+                    {buttons && (
+                      <div className={styles.actions}>
+                        {Array.isArray(buttons) &&
+                          buttons.map((buttonArgs, index) => (
+                            <Button
+                              key={index}
+                              size={'small'}
+                              variant={'text'}
+                              {...buttonArgs}
+                            />
+                          ))}
+                      </div>
+                    )}
+                  </>
+                )}
+              </div>
+            </motion.div>
+          </SyncedFixedWrapper>
+        )}
+      </AnimatePresence>
+    </>
+  );
+};

package/src/lib/components/index.ts

@@ -23,4 +23,4 @@ export * from './TabPanel';
 export * from './TextField';
 export * from './NavigationRailItem';
 export * from './NavigationRail';
-export * from './ToolTip';
+export * from './Tooltip';

package/src/lib/hooks/index.ts

@@ -0,0 +1,11 @@
+export { useTooltipTrigger } from './useTooltipTrigger';
+export type {
+  UseTooltipTriggerOptions,
+  UseTooltipTriggerReturn,
+} from './useTooltipTrigger';
+
+export { useTooltipPosition } from './useTooltipPosition';
+export type {
+  UseTooltipPositionOptions,
+  UseTooltipPositionReturn,
+} from './useTooltipPosition';

package/src/lib/hooks/useTooltipPosition.ts

@@ -0,0 +1,95 @@
+import { RefObject, useLayoutEffect, useState } from 'react';
+
+type Position =
+  | 'top'
+  | 'bottom'
+  | 'left'
+  | 'right'
+  | 'top-left'
+  | 'top-right'
+  | 'bottom-left'
+  | 'bottom-right';
+
+type Variant = 'plain' | 'rich';
+
+export interface UseTooltipPositionOptions {
+  targetRef: RefObject<HTMLElement | null>;
+  position?: Position;
+  variant?: Variant;
+  isOpen: boolean;
+}
+
+export interface UseTooltipPositionReturn {
+  resolvedPosition: Position;
+}
+
+/**
+ * Hook to calculate tooltip position using useLayoutEffect.
+ * Auto-flips position if not enough viewport space.
+ *
+ * For plain variant: prefers left/right, falls back to top/bottom
+ * For rich variant: uses corner positions (top-left, top-right, bottom-left, bottom-right)
+ */
+export function useTooltipPosition({
+  targetRef,
+  position: positionProp,
+  variant = 'plain',
+  isOpen,
+}: UseTooltipPositionOptions): UseTooltipPositionReturn {
+  const [resolvedPosition, setResolvedPosition] = useState<Position>(
+    positionProp ?? 'bottom',
+  );
+
+  useLayoutEffect(() => {
+    // If position is explicitly set, use it
+    if (positionProp) {
+      setResolvedPosition(positionProp);
+      return;
+    }
+
+    // Only calculate if open and we have a target
+    if (!isOpen || !targetRef.current || typeof window === 'undefined') {
+      return;
+    }
+
+    const targetElement = targetRef.current;
+    const rect = targetElement.getBoundingClientRect();
+
+    const viewportWidth = window.innerWidth;
+    const viewportHeight = window.innerHeight;
+
+    // Normalized position (0-1 range)
+    const x = rect.left / viewportWidth;
+    const y = rect.top / viewportHeight;
+
+    let newPosition: Position;
+
+    if (variant === 'plain') {
+      // Plain variant: prefer horizontal positioning, fall back to vertical
+      if (x < 1 / 3) {
+        newPosition = 'right';
+      } else if (x > 2 / 3) {
+        newPosition = 'left';
+      } else {
+        newPosition = y > 0.5 ? 'top' : 'bottom';
+      }
+    } else {
+      // Rich variant: use corner positions
+      if (x < 0.5 && y < 0.5) {
+        newPosition = 'bottom-right';
+      } else if (x >= 0.5 && y < 0.5) {
+        newPosition = 'bottom-left';
+      } else if (x >= 0.5 && y >= 0.5) {
+        newPosition = 'top-left';
+      } else {
+        newPosition = 'top-right';
+      }
+    }
+
+    setResolvedPosition(newPosition);
+  }, [isOpen, targetRef, positionProp, variant]);
+
+  return {
+    resolvedPosition,
+  };
+}

package/src/lib/hooks/useTooltipTrigger.ts

@@ -0,0 +1,270 @@
+import { useCallback, useEffect, useId, useRef, useState } from 'react';
+
+type Trigger = 'hover' | 'click' | 'focus' | null;
+
+type TooltipState = 'hidden' | 'hovered' | 'focused' | 'clicked';
+
+export interface UseTooltipTriggerOptions {
+  trigger?: Trigger | Trigger[];
+  isOpen?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  openDelay?: number;
+  closeDelay?: number;
+  id?: string;
+}
+
+export interface UseTooltipTriggerReturn {
+  triggerProps: {
+    'aria-describedby': string | undefined;
+    onMouseEnter: () => void;
+    onMouseLeave: () => void;
+    onFocus: () => void;
+    onBlur: () => void;
+    onClick: () => void;
+    onKeyDown: (event: React.KeyboardEvent) => void;
+  };
+  tooltipProps: {
+    id: string;
+    role: 'tooltip';
+    'aria-hidden': boolean;
+    onMouseEnter: () => void;
+    onMouseLeave: () => void;
+  };
+  isOpen: boolean;
+  state: TooltipState;
+}
+
+/**
+ * Hook to manage tooltip trigger state machine, events, and accessibility props.
+ *
+ * State Machine:
+ * - States: hidden | hovered | focused | clicked
+ * - Priority: clicked > focused > hovered > hidden
+ * - Focus takes priority over hover (don't close on mouse leave if focused)
+ * - Escape key closes tooltip from any open state
+ * - Click toggles for 'click' trigger
+ */
+export function useTooltipTrigger({
+  trigger = ['hover', 'focus'],
+  isOpen: isOpenProp,
+  defaultOpen = false,
+  onOpenChange,
+  openDelay = 400,
+  closeDelay = 150,
+  id: idProp,
+}: UseTooltipTriggerOptions = {}): UseTooltipTriggerReturn {
+  const generatedId = useId();
+  const tooltipId = idProp ?? `tooltip-${generatedId}`;
+
+  // Normalize trigger to array
+  const triggers = Array.isArray(trigger) ? trigger : [trigger];
+
+  // Controlled vs uncontrolled state
+  const isControlled = typeof isOpenProp === 'boolean';
+  const [internalState, setInternalState] = useState<TooltipState>(
+    defaultOpen ? 'hovered' : 'hidden',
+  );
+
+  // Track if tooltip content is being hovered (for pointer intent)
+  const [isTooltipHovered, setIsTooltipHovered] = useState(false);
+
+  // Timeout refs for delayed open/close
+  const openTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const closeTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Clear all timeouts
+  const clearTimeouts = useCallback(() => {
+    if (openTimeoutRef.current) {
+      clearTimeout(openTimeoutRef.current);
+      openTimeoutRef.current = null;
+    }
+    if (closeTimeoutRef.current) {
+      clearTimeout(closeTimeoutRef.current);
+      closeTimeoutRef.current = null;
+    }
+  }, []);
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => clearTimeouts();
+  }, [clearTimeouts]);
+
+  // State transition function
+  const transition = useCallback(
+    (newState: TooltipState) => {
+      if (isControlled) {
+        // In controlled mode, notify parent of desired state change
+        const shouldBeOpen = newState !== 'hidden';
+        onOpenChange?.(shouldBeOpen);
+      } else {
+        setInternalState(newState);
+        const shouldBeOpen = newState !== 'hidden';
+        onOpenChange?.(shouldBeOpen);
+      }
+    },
+    [isControlled, onOpenChange],
+  );
+
+  // Compute actual state and isOpen
+  const state = isControlled
+    ? isOpenProp
+      ? 'hovered' // Simplified: in controlled mode, we just track open/closed
+      : 'hidden'
+    : internalState;
+
+  const isOpen = state !== 'hidden';
+
+  // Get state priority for comparison
+  const getStatePriority = (s: TooltipState): number => {
+    switch (s) {
+      case 'hidden':
+        return 0;
+      case 'hovered':
+        return 1;
+      case 'focused':
+        return 2;
+      case 'clicked':
+        return 3;
+      default:
+        return 0;
+    }
+  };
+
+  // Schedule opening with delay
+  const scheduleOpen = useCallback(
+    (targetState: TooltipState) => {
+      clearTimeouts();
+
+      // Only transition if new state has higher priority
+      if (getStatePriority(targetState) <= getStatePriority(state)) {
+        return;
+      }
+
+      openTimeoutRef.current = setTimeout(() => {
+        transition(targetState);
+      }, openDelay);
+    },
+    [clearTimeouts, openDelay, state, transition],
+  );
+
+  // Schedule closing with delay
+  const scheduleClose = useCallback(
+    (fromState: TooltipState) => {
+      clearTimeouts();
+
+      closeTimeoutRef.current = setTimeout(() => {
+        // Only close if we're still in the same state (or lower priority)
+        if (
+          !isControlled &&
+          getStatePriority(internalState) <= getStatePriority(fromState)
+        ) {
+          transition('hidden');
+        } else if (isControlled) {
+          transition('hidden');
+        }
+      }, closeDelay);
+    },
+    [clearTimeouts, closeDelay, internalState, isControlled, transition],
+  );
+
+  // Event handlers for trigger element
+  const handleMouseEnter = useCallback(() => {
+    if (!triggers.includes('hover')) return;
+    scheduleOpen('hovered');
+  }, [triggers, scheduleOpen]);
+
+  const handleMouseLeave = useCallback(() => {
+    if (!triggers.includes('hover')) return;
+
+    // Don't close if focused (focus has higher priority)
+    if (state === 'focused' || state === 'clicked') return;
+
+    // Don't close immediately if tooltip itself is hovered
+    if (isTooltipHovered) return;
+
+    scheduleClose('hovered');
+  }, [triggers, state, isTooltipHovered, scheduleClose]);
+
+  const handleFocus = useCallback(() => {
+    if (!triggers.includes('focus')) return;
+    clearTimeouts();
+    transition('focused');
+  }, [triggers, clearTimeouts, transition]);
+
+  const handleBlur = useCallback(() => {
+    if (!triggers.includes('focus')) return;
+
+    // Don't close if clicked (clicked has higher priority)
+    if (state === 'clicked') return;
+
+    // If also hovering, transition to hovered state
+    if (triggers.includes('hover') && isTooltipHovered) {
+      transition('hovered');
+      return;
+    }
+
+    scheduleClose('focused');
+  }, [triggers, state, isTooltipHovered, scheduleClose, transition]);
+
+  const handleClick = useCallback(() => {
+    if (!triggers.includes('click')) return;
+
+    clearTimeouts();
+
+    // Toggle behavior for click trigger
+    if (state === 'clicked') {
+      transition('hidden');
+    } else {
+      transition('clicked');
+    }
+  }, [triggers, state, clearTimeouts, transition]);
+
+  const handleKeyDown = useCallback(
+    (event: React.KeyboardEvent) => {
+      // Escape closes tooltip from any open state
+      if (event.key === 'Escape' && isOpen) {
+        clearTimeouts();
+        transition('hidden');
+        event.preventDefault();
+      }
+    },
+    [isOpen, clearTimeouts, transition],
+  );
+
+  // Event handlers for tooltip element (pointer intent)
+  const handleTooltipMouseEnter = useCallback(() => {
+    setIsTooltipHovered(true);
+    clearTimeouts();
+  }, [clearTimeouts]);
+
+  const handleTooltipMouseLeave = useCallback(() => {
+    setIsTooltipHovered(false);
+
+    // If trigger includes hover and we're in hover state, schedule close
+    if (triggers.includes('hover') && state === 'hovered') {
+      scheduleClose('hovered');
+    }
+  }, [triggers, state, scheduleClose]);
+
+  return {
+    triggerProps: {
+      'aria-describedby': isOpen ? tooltipId : undefined,
+      onMouseEnter: handleMouseEnter,
+      onMouseLeave: handleMouseLeave,
+      onFocus: handleFocus,
+      onBlur: handleBlur,
+      onClick: handleClick,
+      onKeyDown: handleKeyDown,
+    },
+    tooltipProps: {
+      id: tooltipId,
+      role: 'tooltip',
+      'aria-hidden': !isOpen,
+      onMouseEnter: handleTooltipMouseEnter,
+      onMouseLeave: handleTooltipMouseLeave,
+    },
+    isOpen,
+    state,
+  };
+}

package/src/lib/index.ts

@@ -1,5 +1,6 @@
 export * from './components';
 export * from './effects';
+export * from './hooks';
 export * from './icon';
 export * from './interfaces';
 export * from './styles';

package/src/lib/interfaces/fab.interface.ts

@@ -1,6 +1,7 @@
 import { ActionOrLink } from '../utils/component';
 import { Transition } from 'motion';
 import { Icon } from '../icon';
+import { ReactNode } from 'react';
 
 export type FabVariant =
   | 'primary'
@@ -12,7 +13,7 @@ export type FabVariant =
 type Props = {
   variant?: FabVariant;
   label?: string;
-  children?: string;
+  children?: ReactNode;
   icon: Icon;
   size?: 'small' | 'medium' | 'large';
   extended?: boolean;

package/src/lib/interfaces/tooltip.interface.ts

@@ -10,7 +10,10 @@ export type ToolTipInterface<T extends HTMLElement = any> = {
   props: {
     variant?: 'plain' | 'rich';
     title?: string;
-    text: string;
+    /** Supporting text for the tooltip. Optional when using `content` prop. */
+    text?: string;
+    /** Custom content slot that replaces title/text/buttons when provided */
+    content?: ReactNode;
     buttons?: ReactProps<ButtonInterface> | ReactProps<ButtonInterface>[];
     position?:
       | 'top'
@@ -23,6 +26,18 @@ export type ToolTipInterface<T extends HTMLElement = any> = {
       | 'bottom-right';
     trigger?: Trigger | Trigger[];
     transition?: Transition;
+    /** Delay in milliseconds before showing the tooltip. Default: 400ms */
+    openDelay?: number;
+    /** Delay in milliseconds before hiding the tooltip. Default: 150ms */
+    closeDelay?: number;
+    /** Controlled mode: explicitly control whether the tooltip is open */
+    isOpen?: boolean;
+    /** Uncontrolled mode: default open state */
+    defaultOpen?: boolean;
+    /** Callback when the open state changes */
+    onOpenChange?: (open: boolean) => void;
+    /** Custom ID for accessibility linking. Auto-generated if not provided. */
+    id?: string;
   } & (
     | {
         children?: never;
@@ -33,5 +48,12 @@ export type ToolTipInterface<T extends HTMLElement = any> = {
         targetRef?: never;
       }
   );
-  elements: ['toolTip', 'container', 'subHead', 'supportingText', 'actions'];
+  elements: [
+    'toolTip',
+    'container',
+    'subHead',
+    'supportingText',
+    'actions',
+    'content',
+  ];
 };

package/src/lib/styles/tooltip.style.ts

@@ -34,6 +34,7 @@ const toolTipConfig: ClassNameComponent<ToolTipInterface> = ({
   actions: classNames('flex gap-10 px-1 mt-2', variant == 'plain' && 'hidden'),
   subHead: classNames('text-title-small mb-1', variant == 'plain' && 'hidden'),
   supportingText: classNames(''),
+  content: classNames('w-full'),
 });
 
 export const toolStyle = defaultClassNames<ToolTipInterface>(