@moneyforward/mfui-components 2.48.1

package/dist/cjs/src/Tooltip/Tooltip.js

@@ -0,0 +1,69 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tooltip = exports.DEFAULT_MAX_WIDTH = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const css_1 = require("../../styled-system/css");
+const recipes_1 = require("../../styled-system/recipes");
+const Typography_1 = require("../Typography");
+const mergeRefs_1 = require("../utilities/dom/mergeRefs");
+const useTooltipDisplayController_1 = require("./hooks/useTooltipDisplayController");
+const ArrowIcon_1 = require("./icons/ArrowIcon");
+const usePopoverController_1 = require("./hooks/usePopoverController");
+const Portal_1 = require("../Portal");
+exports.DEFAULT_MAX_WIDTH = '268px';
+/**
+ * The general-purpose Tooltip component.
+ * This component extends the props of `<span>` element.
+ *
+ * ## Class Name Usage
+ *
+ * The component supports two types of class name customization:
+ * - `className`: Applied to the root wrapper element that contains the trigger children
+ * - `contentProps.className`: Applied to the floating tooltip content element
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with tooltip content styling
+ * <Tooltip
+ *   contentProps={{ className: 'custom-tooltip' }}
+ *   content="Styled tooltip"
+ * >
+ *   <Button>Trigger</Button>
+ * </Tooltip>
+ *
+ * // Usage with both root and tooltip styling
+ * <Tooltip
+ *   className="wrapper-styling"
+ *   contentProps={{ className: 'tooltip-styling' }}
+ *   content="Fully styled"
+ * >
+ *   <Button>Trigger</Button>
+ * </Tooltip>
+ * ```
+ */
+exports.Tooltip = (0, react_1.forwardRef)(({ children, open, 
+// This prop will be removed in the next major version
+// eslint-disable-next-line @typescript-eslint/no-deprecated
+onOpenStateChange, onOpenStateChanged, content, targetDOMNode, placement, trigger = ['hover', 'focus'], disabled = false, maxWidth = exports.DEFAULT_MAX_WIDTH, className, contentProps, ...wrapperProps }, ref) => {
+    const rootRef = (0, react_1.useRef)(null);
+    const arrowRef = (0, react_1.useRef)(null);
+    const tooltipId = (0, react_1.useId)();
+    // Use automatic target resolution matching Portal.tsx pattern
+    // Resolution order: explicit prop → parent context → document.body fallback
+    const targetElement = (0, Portal_1.useAutomaticTargetDomNode)(targetDOMNode, rootRef.current);
+    const { open: calculatedOpen, rootAttributes, tooltipAttributes, } = (0, useTooltipDisplayController_1.useTooltipDisplayController)({
+        trigger,
+        wrapperProps,
+        tooltipOpen: open,
+        onOpenStateChange: onOpenStateChanged ?? onOpenStateChange,
+        disabled,
+    });
+    const { tooltip: { setReference: setTooltipReference, style: tooltipStyles }, trigger: { setReference: setTriggerReference }, arrow: { style: arrowStyles }, calculatedPlacement, } = (0, usePopoverController_1.usePopoverController)({ placement, open: calculatedOpen, arrowRef });
+    const triggerRef = (0, mergeRefs_1.mergeRefs)(setTriggerReference, rootRef, ref);
+    const classes = (0, recipes_1.tooltipSlotRecipe)();
+    return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)("div", { ref: triggerRef, ...wrapperProps, className: (0, css_1.cx)(classes.root, 'mfui-Tooltip__root', className), ...rootAttributes, children: (0, react_1.isValidElement)(children) ? ((0, react_1.cloneElement)(children, calculatedOpen ? { 'aria-describedby': tooltipId } : undefined)) : ((0, jsx_runtime_1.jsx)("span", { ...(calculatedOpen ? { 'aria-describedby': tooltipId } : undefined), children: children })) }), calculatedOpen ? ((0, jsx_runtime_1.jsx)(Portal_1.Portal, { targetDOMNode: targetElement, children: (0, jsx_runtime_1.jsxs)("div", { ref: setTooltipReference, className: (0, css_1.cx)(classes.tooltip, 'mfui-Tooltip__tooltip', contentProps?.className), role: "tooltip", id: tooltipId, style: { maxWidth, ...tooltipStyles }, ...tooltipAttributes, children: [typeof content === 'string' ? (0, jsx_runtime_1.jsx)(Typography_1.Typography, { variant: "helpMessage", children: content }) : content, (0, jsx_runtime_1.jsx)(ArrowIcon_1.ArrowIcon, { ref: arrowRef, "aria-hidden": true, placement: calculatedPlacement, className: (0, css_1.cx)(classes.arrow, 'mfui-Tooltip__arrow'), style: arrowStyles })] }) })) : null] }));
+});

package/dist/cjs/src/Tooltip/Tooltip.types.d.ts

@@ -0,0 +1,125 @@
+import { type ComponentPropsWithoutRef, type CSSProperties, type ReactNode } from 'react';
+/**
+ * The trigger type of the tooltip.
+ *
+ * This is how the tooltip will be shown, it can be 'hover', 'click', or 'focus'.
+ */
+export type TooltipTriggerType = 'hover' | 'click' | 'focus';
+type Side = 'top' | 'right' | 'bottom' | 'left';
+type Alignment = 'start' | 'end';
+export type TooltipPlacement = Side | `${Side}${Capitalize<Alignment>}`;
+export type TooltipProps = {
+    /**
+     * The trigger element of the tooltip.
+     */
+    children?: ReactNode;
+    /**
+     * Controls the visibility of the tooltip.
+     * If not specified, the tooltip will automatically show or hidden by using trigger.
+     *
+     * @default undefined
+     */
+    open?: boolean;
+    /**
+     * Callback function that will be called when the open state of the tooltip is changed.
+     *
+     * @default undefined
+     *
+     * @deprecated You should use `onOpenStateChanged` instead
+     */
+    onOpenStateChange?: (open: boolean) => void;
+    /**
+     * Callback fired when the open state of the Tooltip changes.
+     *
+     * @param open - The new open state of the Tooltip.
+     *
+     * @default undefined
+     */
+    onOpenStateChanged?: (open: boolean) => void;
+    /**
+     * The content of the tooltip.
+     *
+     * @default undefined
+     */
+    content?: ReactNode;
+    /**
+     * The tooltip placement.
+     *
+     * - Single value: Fixed positioning (e.g., `"top"`)
+     * - Array: Priority-based positioning with fallbacks (e.g., `["top", "bottom"]`)
+     *
+     * When an array is provided, the tooltip will attempt to position itself
+     * using the first placement that fits within the viewport, falling back
+     * to subsequent placements if needed.
+     *
+     * @default "top"
+     *
+     * @example
+     * ```tsx
+     * // Fixed positioning
+     * <Tooltip placement="top">Fixed top positioning</Tooltip>
+     *
+     * // Priority-based positioning with fallbacks
+     * <Tooltip placement={["top", "bottom", "left", "right"]}>
+     *   Smart positioning with fallbacks
+     * </Tooltip>
+     * ```
+     */
+    placement?: TooltipPlacement | TooltipPlacement[];
+    /**
+     * Tooltip trigger mode. It can be a string or an array of strings.
+     *
+     * @default ['hover', 'focus']
+     */
+    trigger?: TooltipTriggerType | TooltipTriggerType[];
+    /**
+     * The DOM node where the tooltip should be rendered.
+     *
+     * If provided, the tooltip is rendered inside this node. Otherwise, a suitable
+     * DOM node is chosen automatically.
+     */
+    targetDOMNode?: HTMLElement | null;
+    /**
+     * If `true`, the tooltip will be disabled, and won't be shown even if the trigger is activated.
+     * But it still follows the `open` prop if it's specified.
+     *
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Sets the maximum width of the tooltip content.
+     *
+     * @default "268px"
+     */
+    maxWidth?: CSSProperties['maxWidth'];
+    /**
+     * Props to be applied to the tooltip content element itself.
+     *
+     * This allows customization of the floating tooltip content, separate from
+     * the root wrapper element that contains the trigger children.
+     *
+     * @property className - The class name for the tooltip content element (not the root wrapper).
+     *
+     * @example
+     * ```tsx
+     * // Applies custom styling to the tooltip content
+     * <Tooltip
+     *   contentProps={{ className: 'my-custom-tooltip' }}
+     *   content="Custom styled tooltip"
+     * >
+     *   <Button>Hover me</Button>
+     * </Tooltip>
+     *
+     * // The className prop applies to the root wrapper
+     * <Tooltip
+     *   className="my-wrapper-class"
+     *   contentProps={{ className: 'my-tooltip-class' }}
+     *   content="Tooltip with both root and content styling"
+     * >
+     *   <Button>Hover me</Button>
+     * </Tooltip>
+     * ```
+     */
+    contentProps?: Pick<ComponentPropsWithoutRef<'div'>, 'className'>;
+} & Omit<ComponentPropsWithoutRef<'span'>, 'content' | 'disabled'>;
+export {};

package/dist/cjs/src/Tooltip/Tooltip.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/src/Tooltip/hooks/useOpenStateDelayed.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A hook to control the display of the tooltip by delaying the open state.
+ * When the tooltip is going to open, it will delay for 250ms before actually visible.
+ * When the tooltip is going to close, it will delay for 750ms before actually invisible.
+ *
+ * @param tooltipOpen - The current open state of the tooltip. If not defined, the tooltip will be controlled by the trigger.
+ *
+ * @param onActualClose - Callback function called when the tooltip actually closes (after delay completes).
+ *
+ * @returns A tuple containing [open, setOpenDelayed, closeImmediate, openImmediate, cancelClose] functions for controlling tooltip state.
+ */
+export declare function useOpenStateDelayed(tooltipOpen?: boolean, onActualClose?: () => void): readonly [boolean, (value: boolean) => void, () => void, () => void, () => void];

package/dist/cjs/src/Tooltip/hooks/useOpenStateDelayed.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useOpenStateDelayed = useOpenStateDelayed;
+const react_1 = require("react");
+const Tooltip_constants_1 = require("../Tooltip.constants");
+/**
+ * A hook to control the display of the tooltip by delaying the open state.
+ * When the tooltip is going to open, it will delay for 250ms before actually visible.
+ * When the tooltip is going to close, it will delay for 750ms before actually invisible.
+ *
+ * @param tooltipOpen - The current open state of the tooltip. If not defined, the tooltip will be controlled by the trigger.
+ *
+ * @param onActualClose - Callback function called when the tooltip actually closes (after delay completes).
+ *
+ * @returns A tuple containing [open, setOpenDelayed, closeImmediate, openImmediate, cancelClose] functions for controlling tooltip state.
+ */
+function useOpenStateDelayed(tooltipOpen, onActualClose) {
+    const [open, setOpen] = (0, react_1.useState)(false);
+    const openTimeout = (0, react_1.useRef)(null);
+    const closeTimeout = (0, react_1.useRef)(null);
+    const setOpenDelayed = (0, react_1.useCallback)((value) => {
+        if (value) {
+            openTimeout.current && clearTimeout(openTimeout.current);
+            closeTimeout.current && clearTimeout(closeTimeout.current);
+            closeTimeout.current = null;
+            openTimeout.current = window.setTimeout(() => {
+                setOpen(true);
+                openTimeout.current = null;
+            }, Tooltip_constants_1.OPEN_DELAY);
+        }
+        else {
+            openTimeout.current && clearTimeout(openTimeout.current);
+            openTimeout.current = null;
+            closeTimeout.current = window.setTimeout(() => {
+                setOpen(false);
+                closeTimeout.current = null;
+                onActualClose?.(); // Notify when tooltip actually closes
+            }, Tooltip_constants_1.CLOSE_DELAY);
+        }
+    }, [onActualClose]);
+    const closeImmediate = (0, react_1.useCallback)(() => {
+        openTimeout.current && clearTimeout(openTimeout.current);
+        closeTimeout.current && clearTimeout(closeTimeout.current);
+        openTimeout.current = null;
+        closeTimeout.current = null;
+        setOpen(false);
+    }, []);
+    const openImmediate = (0, react_1.useCallback)(() => {
+        openTimeout.current && clearTimeout(openTimeout.current);
+        closeTimeout.current && clearTimeout(closeTimeout.current);
+        openTimeout.current = null;
+        closeTimeout.current = null;
+        setOpen(true);
+    }, []);
+    const cancelClose = (0, react_1.useCallback)(() => {
+        if (closeTimeout.current) {
+            clearTimeout(closeTimeout.current);
+            closeTimeout.current = null;
+        }
+    }, []);
+    // Set the open state to the tooltipOpen state when it is defined
+    (0, react_1.useEffect)(() => {
+        if (tooltipOpen !== undefined) {
+            if (tooltipOpen) {
+                setOpen(true); // No delay for programmatic control
+            }
+            else {
+                setOpen(false);
+            }
+        }
+        return () => {
+            openTimeout.current && clearTimeout(openTimeout.current);
+            closeTimeout.current && clearTimeout(closeTimeout.current);
+        };
+    }, [tooltipOpen]);
+    return [open, setOpenDelayed, closeImmediate, openImmediate, cancelClose];
+}

package/dist/cjs/src/Tooltip/hooks/usePopoverController.d.ts

@@ -0,0 +1,44 @@
+import { type CSSProperties } from 'react';
+import { type TooltipPlacement } from '../Tooltip.types';
+/**
+ * The props for the usePopoverController hook.
+ */
+type UsePopoverControllerProps = {
+    /**
+     * The position of the tooltip.
+     * - Single value: Fixed positioning
+     * - Array: Priority-based positioning
+     * - Undefined: Automatic positioning
+     */
+    placement?: TooltipPlacement | TooltipPlacement[];
+    /**
+     * The open state of the tooltip.
+     */
+    open?: boolean;
+    /**
+     * The ref of the arrow element.
+     * This is used to position the arrow.
+     */
+    arrowRef: React.RefObject<Element | null>;
+};
+/**
+ * A hook to control the popover positioning.
+ *
+ * @param options - The options to control the popover.
+ *
+ * @returns The data to map with elements.
+ */
+export declare const usePopoverController: ({ placement, open, arrowRef }: UsePopoverControllerProps) => {
+    tooltip: {
+        setReference: (node: HTMLElement | null) => void;
+        style: CSSProperties;
+    };
+    trigger: {
+        setReference: (node: import("@floating-ui/react-dom").ReferenceType | null) => void;
+    };
+    arrow: {
+        style: CSSProperties;
+    };
+    calculatedPlacement: TooltipPlacement;
+};
+export {};

package/dist/cjs/src/Tooltip/hooks/usePopoverController.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usePopoverController = void 0;
+const react_dom_1 = require("@floating-ui/react-dom");
+const Tooltip_constants_1 = require("../Tooltip.constants");
+// Mapping from original placements to Floating UI placements
+const placementMapping = {
+    top: 'top',
+    topStart: 'top-start',
+    topEnd: 'top-end',
+    bottom: 'bottom',
+    bottomStart: 'bottom-start',
+    bottomEnd: 'bottom-end',
+    left: 'left',
+    leftStart: 'left-start',
+    leftEnd: 'left-end',
+    right: 'right',
+    rightStart: 'right-start',
+    rightEnd: 'right-end',
+};
+// Reverse mapping from Floating UI placements to original placements
+const reversePlacementMapping = {
+    top: 'top',
+    'top-start': 'topStart',
+    'top-end': 'topEnd',
+    bottom: 'bottom',
+    'bottom-start': 'bottomStart',
+    'bottom-end': 'bottomEnd',
+    left: 'left',
+    'left-start': 'leftStart',
+    'left-end': 'leftEnd',
+    right: 'right',
+    'right-start': 'rightStart',
+    'right-end': 'rightEnd',
+};
+/**
+ * A hook to control the popover positioning.
+ *
+ * @param options - The options to control the popover.
+ *
+ * @returns The data to map with elements.
+ */
+const usePopoverController = ({ placement, open, arrowRef }) => {
+    // Handle position prop - can be single value or array
+    const allowedPlacements = placement
+        ? Array.isArray(placement)
+            ? placement.map((pos) => placementMapping[pos]) // Array: priority-based positioning
+            : [placementMapping[placement]] // Single value: fixed positioning
+        : undefined; // Undefined: automatic positioning
+    const { floatingStyles, placement: calculatedPlacement, refs: { setFloating, setReference }, middlewareData: { arrow: arrowData }, } = (0, react_dom_1.useFloating)({
+        open,
+        middleware: [
+            // When we specified placement or allowedPositions, the autoPlacement middleware will be configured accordingly
+            (0, react_dom_1.autoPlacement)({ allowedPlacements }), // Automatically calculates the placement
+            (0, react_dom_1.flip)(), // Flips the tooltip if it goes out of bounds
+            (0, react_dom_1.shift)(), // Shifts the tooltip to stay within the viewport
+            (0, react_dom_1.arrow)({
+                element: arrowRef,
+                padding: {
+                    top: Tooltip_constants_1.ARROW_PADDING,
+                    right: Tooltip_constants_1.ARROW_PADDING,
+                    bottom: Tooltip_constants_1.ARROW_PADDING,
+                    left: Tooltip_constants_1.ARROW_PADDING,
+                },
+            }),
+            (0, react_dom_1.offset)((state) => ({
+                mainAxis: state.placement.startsWith('left') || state.placement.startsWith('right')
+                    ? Tooltip_constants_1.ARROW_WIDTH_HORIZONTAL
+                    : Tooltip_constants_1.ARROW_HEIGHT_VERTICAL,
+            })), // Offset the tooltip,
+        ],
+        strategy: 'fixed',
+        whileElementsMounted: react_dom_1.autoUpdate,
+    });
+    // Convert calculated placement back to original placement
+    const originalPlacement = reversePlacementMapping[calculatedPlacement];
+    return {
+        tooltip: {
+            setReference: setFloating,
+            style: floatingStyles,
+        },
+        trigger: {
+            setReference,
+        },
+        arrow: {
+            style: {
+                position: 'absolute',
+                top: (() => {
+                    // When placement is top, the arrow should be at the bottom
+                    if (originalPlacement.startsWith('top'))
+                        return '100%';
+                    return arrowData?.y ? `${String(arrowData.y)}px` : undefined;
+                })(),
+                right: originalPlacement.startsWith('right') ? '100%' : undefined,
+                left: (() => {
+                    // When placement is left, the arrow should be at the right
+                    if (originalPlacement.startsWith('left'))
+                        return '100%';
+                    return arrowData?.x ? `${String(arrowData.x)}px` : undefined;
+                })(),
+                bottom: originalPlacement.startsWith('bottom') ? '100%' : undefined,
+                // Rotate the arrow if it's on the bottom or right
+                transform: `rotate(${originalPlacement.startsWith('bottom') || originalPlacement.startsWith('right') ? '180deg' : '0'})`,
+            },
+        },
+        calculatedPlacement: originalPlacement, // Return the original placement
+    };
+};
+exports.usePopoverController = usePopoverController;

package/dist/cjs/src/Tooltip/hooks/useTooltipDisplayController.d.ts

@@ -0,0 +1,36 @@
+import { type ComponentPropsWithoutRef } from 'react';
+import { type TooltipTriggerType } from '../Tooltip.types';
+/**
+ * A hook to control the display of the tooltip.
+ *
+ * @param options - The options to control the tooltip display.
+ *
+ * @param options.trigger - The trigger type of the tooltip. Available options are 'hover', 'click', and 'focus'.
+ *
+ * @param options.wrapperProps - The props of the wrapper component which wraps the trigger element. This function will create new props for the wrapper component based on the old ones to support the tooltip trigger.
+ *
+ * @param options.tooltipOpen - The current open state of the tooltip. If not defined, the tooltip will be controlled by the trigger.
+ *
+ * @param options.onOpenStateChange - A callback function that will be called when the open state of the tooltip changes.
+ *
+ * @param options.disabled - If `true`, the tooltip will be disabled, and won't be shown even if the trigger is activated, but it still follows the `tooltipOpen` prop if it's specified.
+ *
+ * @returns An object containing the opening state, the root attributes, and tooltip attributes.
+ */
+export declare function useTooltipDisplayController({ trigger, wrapperProps, tooltipOpen, onOpenStateChange, disabled, }: {
+    trigger: TooltipTriggerType | TooltipTriggerType[];
+    wrapperProps: ComponentPropsWithoutRef<'span'>;
+    tooltipOpen?: boolean;
+    onOpenStateChange?: (open: boolean) => void;
+    disabled: boolean;
+}): {
+    open: boolean;
+    rootAttributes: Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref">;
+    tooltipAttributes: {
+        onMouseEnter?: undefined;
+        onMouseLeave?: undefined;
+    } | {
+        onMouseEnter: () => void;
+        onMouseLeave: () => void;
+    };
+};