@udixio/ui-react 2.9.7 → 2.9.9

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/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/card.style.ts

@@ -11,10 +11,13 @@ const cardConfig: ClassNameComponent<CardInterface> = ({
   isInteractive,
 }) => ({
   card: classNames(
-    'group/card rounded-xl overflow-hidden z-10',
+    ' rounded-xl overflow-hidden ',
     variant === 'outlined' && 'bg-surface border border-outline-variant',
     variant === 'elevated' && 'bg-surface-container-low shadow-1',
     variant === 'filled' && 'bg-surface-container-highest',
+    {
+      'group/card': isInteractive,
+    },
   ),
 });
 

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>(

package/src/stories/communication/tool-tip.stories.tsx

@@ -1,10 +1,10 @@
 import type { Meta, StoryObj } from '@storybook/react';
-import { Button, ReactProps, ToolTip, ToolTipInterface } from '../../lib';
+import { Button, ReactProps, Tooltip, ToolTipInterface } from '../../lib';
 
 // More on how to set up stories at: https://storybook.js.org/docs/react/writing-stories/introduction#default-export
 const meta = {
   title: 'Communication/ToolTip',
-  component: ToolTip,
+  component: Tooltip,
   parameters: {
     // Optional parameter to center the component in the Canvas. More info: https://storybook.js.org/docs/react/configure/story-layout
   },
@@ -12,7 +12,7 @@ const meta = {
   tags: ['autodocs'],
   // More on argTypes: https://storybook.js.org/docs/react/api/argtypes
   argTypes: {},
-} satisfies Meta<typeof ToolTip>;
+} satisfies Meta<typeof Tooltip>;
 
 export default meta;
 type Story = StoryObj<typeof meta>;
@@ -27,84 +27,84 @@ const createToolTipStory = (
     <div className="h-96 relative">
       <div className="h-96 relative">
         <div className="absolute top-0 left-0">
-          <ToolTip
+          <Tooltip
             position="bottom-right"
             {...args}
             text="Cliquez pour plus d'infos"
             title="Info rapide"
           >
             <Button variant={'filledTonal'} label={'Bottom-right'}></Button>
-          </ToolTip>
+          </Tooltip>
         </div>
         <div className="absolute top-0 left-1/2 -translate-x-1/2">
-          <ToolTip
+          <Tooltip
             position="bottom"
             {...args}
             text="Cet élément représente les statistiques globales de votre projet."
             title="Statistiques"
           >
             <Button variant={'filledTonal'} label={'Bottom-center'}></Button>
-          </ToolTip>
+          </Tooltip>
         </div>
         <div className="absolute top-0 right-0">
-          <ToolTip
+          <Tooltip
             position="bottom-left"
             {...args}
             text="Cliquez ici pour télécharger le fichier associé."
             title="Téléchargement"
           >
             <Button variant={'filledTonal'} label={'Bottom-left'}></Button>
-          </ToolTip>
+          </Tooltip>
         </div>
         <div className="absolute top-1/2 left-0 -translate-y-1/2">
-          <ToolTip
+          <Tooltip
             position="right"
             {...args}
             text="Cette action ne peut pas être annulée une fois confirmée."
             title="Attention"
           >
             <Button variant={'filledTonal'} label={'Center-right'}></Button>
-          </ToolTip>
+          </Tooltip>
         </div>
         <div className="absolute top-1/2 right-0 -translate-y-1/2">
-          <ToolTip
+          <Tooltip
             position="left"
             {...args}
             text="Modifiez les paramètres dans l'onglet dédié à la personnalisation."
             title="Personnalisation"
           >
             <Button variant={'filledTonal'} label={'Center-left'}></Button>
-          </ToolTip>
+          </Tooltip>
         </div>
         <div className="absolute bottom-0 left-0">
-          <ToolTip
+          <Tooltip
             position="top-right"
             {...args}
             text="L'action demandée supprimera toutes les données correspondantes."
             title="Suppression de données"
           >
             <Button variant={'filledTonal'} label={'Top-right'}></Button>
-          </ToolTip>
+          </Tooltip>
         </div>
         <div className="absolute bottom-0 left-1/2 -translate-x-1/2">
-          <ToolTip
+          <Tooltip
             position="top"
             {...args}
             text="Double-cliquez pour agrandir l'aperçu de l'élément sélectionné."
             title="Aperçu"
           >
             <Button variant={'filledTonal'} label={'Top-center'}></Button>
-          </ToolTip>
+          </Tooltip>
         </div>
         <div className="absolute bottom-0 right-0">
-          <ToolTip
+          <Tooltip
             position="top-left"
             {...args}
             text="Passez la souris sur d'autres icônes pour plus de détails."
             title="Icones et navigation"
           >
             <Button variant={'filledTonal'} label={'Top-left'}></Button>
-          </ToolTip>
+          </Tooltip>
         </div>
       </div>
     </div>

package/tsconfig.json

@@ -3,12 +3,6 @@
   "files": [],
   "include": [],
   "references": [
-    {
-      "path": "../tailwind"
-    },
-    {
-      "path": "../theme"
-    },
     {
       "path": "./tsconfig.lib.json"
     },

package/dist/lib/components/ToolTip.d.ts

@@ -1,9 +0,0 @@
-import { MotionProps } from '../utils';
-import { ToolTipInterface } from '../interfaces';
-/**
- * Tooltips display brief labels or messages
- * @status beta
- * @category Communication
- */
-export declare const ToolTip: ({ variant, buttons, className, children, title, text, position, targetRef, ref, trigger, transition, ...props }: MotionProps<ToolTipInterface>) => import("react/jsx-runtime").JSX.Element;
-//# sourceMappingURL=ToolTip.d.ts.map

package/dist/lib/components/ToolTip.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ToolTip.d.ts","sourceRoot":"","sources":["../../../src/lib/components/ToolTip.tsx"],"names":[],"mappings":"AAOA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAMjD;;;;GAIG;AACH,eAAO,MAAM,OAAO,GAAI,iHAarB,WAAW,CAAC,gBAAgB,CAAC,4CA8N/B,CAAC"}