@moneyforward/mfui-components 2.48.1

package/dist/esm/src/Panel/Panel.types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/src/Panel/index.d.ts

@@ -0,0 +1,2 @@
+export { Panel } from './Panel';
+export type { PanelProps } from './Panel.types';

package/dist/esm/src/Panel/index.js

@@ -0,0 +1 @@
+export { Panel } from './Panel';

package/dist/esm/src/Popover/Popover.d.ts

@@ -0,0 +1,9 @@
+import { type PopoverProps } from './Popover.types';
+/**
+ * The Popover component.
+ * This component is a foundation component for other Popover components like SelectBox, MultipleSelectBox, DropdownMenu, DatePicker, etc
+ *
+ * You can control the open state of the Popover by passing the `open` and `onOpenStateChanged` props
+ * Or just leave it as an uncontrolled popover, it will automatically handle by itself.
+ */
+export declare function Popover({ renderTrigger, renderContent, open, onOpenStateChanged, onOpen, onClose, enableAutoFocusOnTrigger, enableAutoFocusOnPopover, minWidth, maxHeight, enableConstrainedContentWidth, contentProps, targetDOMNode, enableAutoUnmount, onBlur, allowedPlacements, enableViewportConstraint, enableAutomaticPortalTargetResolution, enableCenteredLayoutOnNarrowViewport, }: PopoverProps): import("react/jsx-runtime").JSX.Element;

package/dist/esm/src/Popover/Popover.js

@@ -0,0 +1,229 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useState, useRef, } from 'react';
+import { PopoverContextProvider, usePopoverContext } from './PopoverContext';
+import { usePopoverMenuPlacement } from '../utilities/dom/usePopoverMenuPlacement';
+import { useDisclosure } from '../utilities/state/useDisclosure';
+import { Portal, TargetDomNodeProvider, useAutomaticTargetDomNode } from '../Portal';
+import { useOnClickOutside } from '../utilities/dom/useOnClickOutside';
+import { getRootNode } from '../utilities/dom/getRootNode';
+import { getTargetDomNode } from '../utilities/dom/getTargetDomNode';
+import { popoverSlotRecipe } from '../../styled-system/recipes';
+import { useUpdateEffect } from '../utilities/effect/useUpdateEffect';
+import { cx } from '../../styled-system/css';
+/**
+ * The Popover component.
+ * This component is a foundation component for other Popover components like SelectBox, MultipleSelectBox, DropdownMenu, DatePicker, etc
+ *
+ * You can control the open state of the Popover by passing the `open` and `onOpenStateChanged` props
+ * Or just leave it as an uncontrolled popover, it will automatically handle by itself.
+ */
+export function Popover({ renderTrigger, renderContent, open, onOpenStateChanged, onOpen, onClose, enableAutoFocusOnTrigger = true, enableAutoFocusOnPopover = true, minWidth, maxHeight, enableConstrainedContentWidth = false, contentProps = {}, targetDOMNode, enableAutoUnmount = true, onBlur, allowedPlacements, enableViewportConstraint = true, enableAutomaticPortalTargetResolution = false, enableCenteredLayoutOnNarrowViewport = false, }) {
+    // Toggle event is the event triggered by open / close the Popover
+    const [toggleEvent, setToggleEvent] = useState();
+    const { isOpen: localIsOpen, toggle: localToggle, open: localOpen, close: localClose, } = useDisclosure({
+        value: open,
+        onToggle: onOpenStateChanged,
+        onOpen: () => {
+            onOpenStateChanged?.(true);
+        },
+        onClose: () => {
+            onOpenStateChanged?.(false);
+        },
+    });
+    const { refs, floatingStyles, update } = usePopoverMenuPlacement({
+        minWidth,
+        maxHeight,
+        allowedPlacements,
+        enableViewportConstraint,
+        constrainToTriggerWidth: enableConstrainedContentWidth,
+        enableCenteredLayoutOnNarrowViewport,
+    });
+    // Fire onOpen / onClose *only* when the open state actually changes.
+    // We keep a ref of the previous open state so a new toggleEvent while already
+    // open does not retrigger `onOpen`, which previously caused unexpected focus
+    // jumps (e.g. selecting an end-date rewrote focus back to start input).
+    const previousOpenRef = useRef(localIsOpen);
+    useUpdateEffect(() => {
+        const wasOpen = previousOpenRef.current;
+        if (!wasOpen && localIsOpen) {
+            // Transition: closed -> open
+            onOpen?.(toggleEvent);
+            if (!toggleEvent?.defaultPrevented && enableAutoFocusOnPopover) {
+                refs.floating.current?.focus({ preventScroll: true });
+            }
+        }
+        else if (wasOpen && !localIsOpen) {
+            // Transition: open -> closed
+            onClose?.(toggleEvent);
+            if (!toggleEvent?.defaultPrevented && enableAutoFocusOnTrigger) {
+                refs.reference.current?.focus();
+            }
+        }
+        // Update tracker for next invocation
+        previousOpenRef.current = localIsOpen;
+    }, [localIsOpen, onOpen, onClose, enableAutoFocusOnPopover, enableAutoFocusOnTrigger]);
+    const handleKeyDownTrigger = useCallback((event) => {
+        switch (event.key) {
+            case 'ArrowDown':
+            case 'ArrowUp':
+                event.stopPropagation();
+                event.preventDefault();
+                setToggleEvent(event);
+                localOpen();
+                break;
+        }
+    }, [localOpen]);
+    const handleKeyDownPopover = useCallback((event) => {
+        switch (event.key) {
+            case 'Escape':
+                event.stopPropagation();
+                event.preventDefault();
+                setToggleEvent(event);
+                localClose();
+                break;
+        }
+    }, [localClose]);
+    // Smart blur detection: only trigger onBlur when focus leaves both trigger and popover
+    const handleTriggerBlur = useCallback((event) => {
+        // Always use setTimeout to check the next focused element after blur event completes
+        // This ensures we correctly handle cases where elements within the trigger area (like clear buttons)
+        // cause blur events but the user is still interacting with the component
+        setTimeout(() => {
+            const triggerElement = refs.reference.current;
+            const popoverElement = refs.floating.current;
+            // Get the appropriate root node for the trigger element
+            const rootNode = getRootNode(triggerElement);
+            // Helper function to check if an element is within the component
+            const isElementWithinComponent = (element) => {
+                if (!element)
+                    return false;
+                // Check if focus is within trigger
+                if (triggerElement && (element === triggerElement || triggerElement.contains(element))) {
+                    return true;
+                }
+                // Check if focus is within popover
+                if (popoverElement && (element === popoverElement || popoverElement.contains(element))) {
+                    return true;
+                }
+                return false;
+            };
+            // Get active elements from all potential sources
+            const shadowActiveElement = rootNode instanceof ShadowRoot ? rootNode.activeElement : null;
+            const documentActiveElement = document.activeElement;
+            // In Shadow DOM environments, we need to handle focus detection differently
+            const isInShadowDOM = rootNode instanceof ShadowRoot;
+            let isFocusStillWithinComponent = false;
+            if (isInShadowDOM) {
+                // In Shadow DOM: check both shadow and document active elements
+                isFocusStillWithinComponent =
+                    isElementWithinComponent(shadowActiveElement) ||
+                        isElementWithinComponent(documentActiveElement);
+                // Special case: If shadow activeElement is null, it means focus has left the shadow DOM.
+                // We should trigger onBlur unless the document activeElement is still within our component
+                // (which would be the case if focus moved to the shadow host or related elements)
+                if (!shadowActiveElement) {
+                    isFocusStillWithinComponent = isElementWithinComponent(documentActiveElement);
+                }
+            }
+            else {
+                // In regular DOM: just check document active element
+                isFocusStillWithinComponent = isElementWithinComponent(documentActiveElement);
+            }
+            // Only trigger onBlur if focus has completely left the component
+            if (!isFocusStillWithinComponent) {
+                onBlur?.(event);
+            }
+        }, 0);
+    }, [onBlur, refs.reference, refs.floating]);
+    // Close the menu when clicking outside the menu
+    useOnClickOutside(refs.floating, (event) => {
+        setToggleEvent(undefined);
+        localClose();
+        // Also trigger onBlur when clicking outside, since this represents the user
+        // clicking away from the component entirely. We create a synthetic FocusEvent
+        // based on the click event for consistency with other blur scenarios.
+        onBlur?.({
+            type: 'blur',
+            target: refs.reference.current,
+            currentTarget: refs.reference.current,
+            relatedTarget: event.target,
+            bubbles: true,
+            cancelable: false,
+            timeStamp: event.timeStamp,
+            nativeEvent: event,
+        });
+    }, { ignoreRefs: [refs.reference] });
+    const options = useMemo(() => {
+        const toggle = (event) => {
+            setToggleEvent(event);
+            localToggle();
+        };
+        const open = (event) => {
+            setToggleEvent(event);
+            localOpen();
+        };
+        const close = (event) => {
+            setToggleEvent(event);
+            localClose();
+        };
+        return {
+            togglePopover: toggle,
+            openPopover: open,
+            closePopover: close,
+            isPopoverOpen: localIsOpen,
+            setTriggerRef: refs.setReference,
+            handleTriggerKeyDown: handleKeyDownTrigger,
+            handleTriggerBlur,
+        };
+    }, [localIsOpen, localOpen, localClose, localToggle, refs, handleKeyDownTrigger, handleTriggerBlur]);
+    const classes = popoverSlotRecipe();
+    /**
+     * useDisclosure delayed updating the value because it uses useEffect to update the value.
+     * To prevent the Popover delays 1 render phase to display, we can use both `open` and `localIsOpen` to check if the
+     * Popover is opening.
+     *
+     * When enableAutoUnmount is true, only render when open (returns null when closed).
+     * When enableAutoUnmount is false, always render but hide via CSS when closed.
+     */
+    const isPopoverOpen = open ?? localIsOpen;
+    const shouldRenderTheContent = enableAutoUnmount ? isPopoverOpen : true;
+    // Get the current nesting context for automatic portal target resolution and depth tracking
+    const { isNested, nestingDepth } = usePopoverContext();
+    // Determine effective target DOM node based on nesting context and enableAutomaticPortalTargetResolution
+    const effectiveTargetDOMNode = useMemo(() => {
+        if (!enableAutomaticPortalTargetResolution || !isNested) {
+            return targetDOMNode;
+        }
+        try {
+            // For nested scenarios, use MFUI's ShadowDOM-compatible target resolution
+            // This will automatically create #mfui-shadow-dom-root in ShadowDOM or use document.body
+            const resolvedNode = getTargetDomNode(undefined, refs.reference.current);
+            return resolvedNode;
+        }
+        catch (error) {
+            // Handle cases where:
+            // 1. Element is not connected to DOM tree (detached elements)
+            // 2. ShadowDOM operations fail
+            // 3. SSR edge cases
+            console.warn('Failed to resolve target DOM node for nested Popover, falling back to original target:', error);
+            return targetDOMNode;
+        }
+    }, [enableAutomaticPortalTargetResolution, isNested, targetDOMNode, refs.reference]);
+    const targetElement = useAutomaticTargetDomNode(effectiveTargetDOMNode, refs.reference.current);
+    /**
+     * The parent element can be animated, like SidePane.
+     * We need to listen to the animationend event to update the floating styles to make sure that the Popover
+     * is in the correct position.
+     */
+    useEffect(() => {
+        targetElement.addEventListener('animationend', update);
+        return () => {
+            targetElement.removeEventListener('animationend', update);
+        };
+    }, [targetElement, update]);
+    return (_jsxs(_Fragment, { children: [renderTrigger(options), shouldRenderTheContent ? (_jsx(Portal, { targetDOMNode: targetElement, children: _jsx("div", { ref: refs.setFloating, tabIndex: contentProps.tabIndex ?? 0, "data-mfui-content": "popover-portal-content", "data-mfui-popover-depth": nestingDepth, className: cx(classes.root, 'mfui-Popover__root', contentProps.className), style: {
+                        ...floatingStyles,
+                        ...(!enableAutoUnmount && !isPopoverOpen && { display: 'none' }),
+                    }, onKeyDown: handleKeyDownPopover, children: _jsx(TargetDomNodeProvider, { targetDomNode: refs.floating.current, children: _jsx(PopoverContextProvider, { children: renderContent(options) }) }) }) })) : null] }));
+}

package/dist/esm/src/Popover/Popover.types.d.ts

@@ -0,0 +1,251 @@
+import { type ComponentProps, type CSSProperties, type KeyboardEventHandler, type ReactNode, type SyntheticEvent, type FocusEventHandler } from 'react';
+type Side = 'top' | 'right' | 'bottom' | 'left';
+type Alignment = 'start' | 'end';
+/**
+ * Placement options for the popover relative to the trigger element.
+ * Follows the same pattern as Floating UI but with our own type definition.
+ */
+export type PopoverPlacement = Side | `${Side}-${Alignment}`;
+/**
+ * Options to control the behavior of the Popover, which be used to render the Trigger and the Popover Content
+ */
+export type PopoverRenderOptions = {
+    /**
+     * If the Popover is opening, close it
+     * If the Popover is closed, open it
+     */
+    togglePopover: (event?: SyntheticEvent) => void;
+    /**
+     * Open the Popover
+     */
+    openPopover: (event?: SyntheticEvent) => void;
+    /**
+     * Close the Popover
+     */
+    closePopover: (event?: SyntheticEvent) => void;
+    /**
+     * Current state of the Popover
+     */
+    isPopoverOpen: boolean;
+    /**
+     * This is required parameter to make the Trigger and the Popover automatically align with each other.
+     *
+     * @param element - The trigger element, must be an HTMLElement like button or div.
+     *
+     * @example
+     * ```tsx
+     * <Popover renderTrigger={({setTriggerRef}) => {
+     *   return <button ref={setTriggerRef} />
+     * }} .../>
+     * ```
+     */
+    setTriggerRef: (element: HTMLElement | null) => void;
+    /**
+     * This is an optional parameter but should be used in the Trigger Element to open the Popover when user press `Up` or `Down` when focusing on the Trigger element
+     *
+     * @example
+     * ```tsx
+     * <Popover renderTrigger={({handleTriggerKeyDown}) => {
+     *   return <button onKeyDown={handleTriggerKeyDown} />
+     * }} .../>
+     * ```
+     */
+    handleTriggerKeyDown: KeyboardEventHandler<HTMLElement>;
+    /**
+     * This is an optional parameter but should be used in the Trigger Element to handle blur events with smart blur detection
+     *
+     * @example
+     * ```tsx
+     * <Popover renderTrigger={({handleTriggerBlur}) => {
+     *   return <button onBlur={handleTriggerBlur} />
+     * }} .../>
+     * ```
+     */
+    handleTriggerBlur: FocusEventHandler<HTMLElement>;
+};
+/**
+ * Props for the Popover component
+ */
+export type PopoverProps = {
+    /**
+     * The function to render a trigger element, you must use the options params to control its behavior.
+     *
+     * @param options - Options to control the behavior of the Popover.
+     */
+    renderTrigger: (options: PopoverRenderOptions) => ReactNode;
+    /**
+     * The content of the Popover.
+     * This is the content inside the popover, not the popover itself.
+     */
+    renderContent: (options: PopoverRenderOptions) => ReactNode;
+    /**
+     * The open state of the Popover.
+     * You only need to use this prop if you want to control the Popover programmatically
+     *
+     * @default false
+     */
+    open?: boolean;
+    /**
+     * Callback fired when the open state of the Popover changes.
+     *
+     * @param open - The new open state of the Popover.
+     */
+    onOpenStateChanged?: (open: boolean) => void;
+    /**
+     * This callback function will be called when the Popover opened.
+     * The default action is focusing on the Popover.
+     * You can prevent that action by using `event.preventDefault()` in the callback function.
+     *
+     * @param event - The trigger event which makes the Popover open, this param can be undefined if you use `toggle` or
+     * `open` without passing the event parameter. If you don't pass the event, you can't prevent the default action.
+     */
+    onOpen?: (event?: SyntheticEvent) => void;
+    /**
+     * This callback function will be called with the Popover closed.
+     * The default action is focusing on the Trigger.
+     * You can prevent that action by using `event.preventDefault()` in the callback function.
+     *
+     * @param event - The trigger event which makes the Popover close, this param can be undefined if you use `toggle` or
+     * `close` without passing the event parameter. If you don't pass the event, you can't prevent the default action.
+     */
+    onClose?: (event?: SyntheticEvent) => void;
+    /**
+     * The flag to enable or disable autofocus on the trigger element when the Popover closes.
+     *
+     * @default true - By default, it will automatically focus on the trigger element when the Popover closes.
+     */
+    enableAutoFocusOnTrigger?: boolean;
+    /**
+     * The flag to enable or disable autofocus on the popover element when the Popover opens.
+     *
+     * @default true - By default, it will automatically focus on the popover element when the popover opens.
+     */
+    enableAutoFocusOnPopover?: boolean;
+    /**
+     * The props for the popover content element.
+     *
+     * @default {}
+     */
+    contentProps?: Pick<ComponentProps<'div'>, 'className'> & {
+        /**
+         * The tab index of the popover content element.
+         * Please note if you set this prop, it may cause the incorrect focus behavior when `enableAutoFocusOnPopover` is true.
+         * You should only set this prop with `enableAutoFocusOnPopover` is false, or the customize focus behavior.
+         *
+         * @default 0
+         */
+        tabIndex?: ComponentProps<'div'>['tabIndex'];
+    };
+    /**
+     * The minimum width of the popover. Default is the width of the trigger element.
+     */
+    minWidth?: CSSProperties['minWidth'];
+    /**
+     * The maximum height of the popover
+     */
+    maxHeight?: CSSProperties['maxHeight'];
+    /**
+     * Whether to constrain the popover content width to exactly match the trigger element width.
+     * When enabled, both minWidth and maxWidth will be set to the trigger width.
+     *
+     * @default false
+     */
+    enableConstrainedContentWidth?: boolean;
+    /**
+     * The DOM node where the popover should be rendered.
+     *
+     * If provided, the popover is rendered inside this node. Otherwise, a suitable
+     * DOM node is chosen automatically.
+     */
+    targetDOMNode?: HTMLElement | null;
+    /**
+     * Enable auto unmounting of the popover content when it's not displayed.
+     * When true, the popover content will return null instead of hiding via CSS.
+     *
+     * @default true
+     */
+    enableAutoUnmount?: boolean;
+    /**
+     * Callback fired when the user blurs away from the trigger element or popover content.
+     * This implements smart blur detection - only fires when focus leaves both the trigger and popover.
+     *
+     * @param event - The blur event from the trigger element
+     */
+    onBlur?: FocusEventHandler<HTMLElement>;
+    /**
+     * Allowed placements for the popover relative to the trigger element.
+     * When provided, the popover will try each placement in order until it finds one that fits within the viewport.
+     *
+     * @default ['bottom-start', 'bottom-end', 'top-start', 'top-end']
+     *
+     * @example
+     * ```tsx
+     * // Try bottom-start first, fallback to top-start
+     * <Popover allowedPlacements={['bottom-start', 'top-start']}>
+     *   ...
+     * </Popover>
+     *
+     * // Allow all bottom placements
+     * <Popover allowedPlacements={['bottom', 'bottom-start', 'bottom-end']}>
+     *   ...
+     * </Popover>
+     * ```
+     */
+    allowedPlacements?: PopoverPlacement[];
+    /**
+     * Whether to enable viewport constraint for the popover content.
+     * When enabled, the popover will be constrained to fit within the viewport and may become scrollable.
+     * When disabled, the popover content can overflow the viewport boundaries.
+     *
+     * This is useful for components like DatePicker where you want the calendar to display fully
+     * even in constrained spaces, rather than being forced to scroll.
+     *
+     * @default true - By default, the popover content is constrained to the viewport for accessibility
+     *
+     * @example
+     * ```tsx
+     * // Default behavior - content constrained to viewport
+     * <Popover enableViewportConstraint={true}>
+     *   ...
+     * </Popover>
+     *
+     * // Allow content to overflow viewport
+     * <Popover enableViewportConstraint={false}>
+     *   ...
+     * </Popover>
+     * ```
+     */
+    enableViewportConstraint?: boolean;
+    /**
+     * Enable automatic portal target resolution for nested Popover scenarios.
+     * Automatically handles ShadowDOM compatibility and nested context detection.
+     * When enabled and the component is nested inside another Popover, automatically
+     * uses getTargetDomNode utility for portal target resolution.
+     *
+     * This prop is intended for internal MFUI components like BasePicker and BaseRangePicker.
+     *
+     * @internal
+     *
+     * @default false
+     */
+    enableAutomaticPortalTargetResolution?: boolean;
+    /**
+     * Enable centered layout on narrow viewport (< 600px).
+     * When enabled, the popover will be centered horizontally on the screen
+     * with 14px margins on both sides, instead of being positioned relative to the trigger.
+     *
+     * This is useful for preventing content from being cut off on narrow viewports.
+     *
+     * @default false
+     *
+     * @example
+     * ```tsx
+     * // Enable centered layout on narrow viewport
+     * <Popover enableCenteredLayoutOnNarrowViewport={true}>
+     *   ...
+     * </Popover>
+     * ```
+     */
+    enableCenteredLayoutOnNarrowViewport?: boolean;
+};
+export {};

package/dist/esm/src/Popover/Popover.types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/src/Popover/PopoverContext.d.ts

@@ -0,0 +1,28 @@
+import React, { type ReactNode } from 'react';
+/**
+ * Context for tracking nested Popover components
+ */
+type PopoverContextValue = {
+    /**
+     * Whether this component is nested inside another Popover
+     */
+    isNested: boolean;
+    /**
+     * The depth of nesting (0 for root level, 1 for first nested level, etc.)
+     */
+    nestingDepth: number;
+};
+/**
+ * Hook to access the popover nesting context
+ *
+ * @returns PopoverContextValue containing nesting information
+ */
+export declare function usePopoverContext(): PopoverContextValue;
+/**
+ * Provider component that tracks nesting depth for Popover components
+ * This replaces the inefficient DOM traversal approach with React Context
+ */
+export declare const PopoverContextProvider: React.MemoExoticComponent<({ children }: {
+    children: ReactNode;
+}) => import("react/jsx-runtime").JSX.Element>;
+export {};

package/dist/esm/src/Popover/PopoverContext.js

@@ -0,0 +1,27 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import React, { createContext, useContext, useMemo } from 'react';
+const PopoverContext = createContext({
+    isNested: false,
+    nestingDepth: 0,
+});
+/**
+ * Hook to access the popover nesting context
+ *
+ * @returns PopoverContextValue containing nesting information
+ */
+export function usePopoverContext() {
+    return useContext(PopoverContext);
+}
+/**
+ * Provider component that tracks nesting depth for Popover components
+ * This replaces the inefficient DOM traversal approach with React Context
+ */
+export const PopoverContextProvider = React.memo(({ children }) => {
+    const parentContext = useContext(PopoverContext);
+    const contextValue = useMemo(() => ({
+        isNested: true, // Any component inside PopoverContextProvider is nested
+        nestingDepth: parentContext.nestingDepth + 1,
+    }), [parentContext.nestingDepth]);
+    return _jsx(PopoverContext.Provider, { value: contextValue, children: children });
+});

package/dist/esm/src/Popover/index.d.ts

@@ -0,0 +1,3 @@
+export { Popover } from './Popover';
+export type { PopoverProps, PopoverRenderOptions, PopoverPlacement } from './Popover.types';
+export { usePopoverContext, PopoverContextProvider } from './PopoverContext';

package/dist/esm/src/Popover/index.js

@@ -0,0 +1,2 @@
+export { Popover } from './Popover';
+export { usePopoverContext, PopoverContextProvider } from './PopoverContext';

package/dist/esm/src/Portal/Portal.d.ts

@@ -0,0 +1,9 @@
+import { type PortalProps } from './Portal.types';
+/**
+ * A component that renders its children into a new "subtree" outside of the parent component.
+ * It is useful for rendering modals, dropdowns, tooltips, and other floating UI elements.
+ *
+ * This behaves the same as `ReactDOM.createPortal`, but adds support for SSR-aware rendering and
+ * automatic resolution of the target DOM node when used with MFUI's portal context utilities.
+ */
+export declare function Portal({ children, targetDOMNode }: PortalProps): import("react").ReactPortal | null;

package/dist/esm/src/Portal/Portal.js

@@ -0,0 +1,19 @@
+'use client';
+import { createPortal } from 'react-dom';
+import { useClosestTargetDomNode } from './TargetDomNodeContext';
+import { useIsServer } from './utils/useIsServer';
+/**
+ * A component that renders its children into a new "subtree" outside of the parent component.
+ * It is useful for rendering modals, dropdowns, tooltips, and other floating UI elements.
+ *
+ * This behaves the same as `ReactDOM.createPortal`, but adds support for SSR-aware rendering and
+ * automatic resolution of the target DOM node when used with MFUI's portal context utilities.
+ */
+export function Portal({ children, targetDOMNode }) {
+    const isServer = useIsServer();
+    const closestTargetDomNode = useClosestTargetDomNode();
+    if (isServer)
+        return null;
+    const targetElement = targetDOMNode ?? closestTargetDomNode ?? document.body;
+    return createPortal(children, targetElement);
+}

package/dist/esm/src/Portal/Portal.types.d.ts

@@ -0,0 +1,22 @@
+import { type createPortal } from 'react-dom';
+/**
+ * Props for the Portal component.
+ *
+ * It simply has the same behavior with `ReactDOM.createPortal`, but with additional support for SSR.
+ *
+ * @see https://react.dev/reference/react-dom/createPortal
+ */
+export type PortalProps = {
+    /**
+     * The content to render in the portal.
+     */
+    children: Parameters<typeof createPortal>[0];
+    /**
+     * The target DOM node to render the children. This corresponds to the second
+     * parameter of `ReactDOM.createPortal`.
+     *
+     * If provided, the children are rendered inside this node. Otherwise, a
+     * suitable DOM node is chosen automatically.
+     */
+    targetDOMNode?: Parameters<typeof createPortal>[1];
+};

package/dist/esm/src/Portal/Portal.types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/src/Portal/TargetDomNodeContext.d.ts

@@ -0,0 +1,22 @@
+import { type PropsWithChildren } from 'react';
+type PortalContextValue = HTMLElement | null;
+export declare const useClosestTargetDomNode: () => PortalContextValue;
+type TargetDomNodeProviderProps = PropsWithChildren<{
+    targetDomNode: PortalContextValue;
+}>;
+/**
+ * This is a wrapper of TargetDomNodeContext.Provider, it provides the targetDomNode to the children.
+ *
+ * When children components use the useClosestTargetDomNode hook, it will return the targetDomNode provided by this component.
+ */
+export declare function TargetDomNodeProvider({ targetDomNode, children }: TargetDomNodeProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * This hook provides the targetDomNode for the Portal component.
+ * It will return the user provided targetDomNode if it is not null, otherwise it will return the closest targetDomNode from the TargetDomNodeContext.
+ *
+ * @param providedTargetDomNode - The targetDomNode provided by the user.
+ *
+ * @param hangingElement - The element to detect the rootNode, if not provided, it will return the body element of the ownerDocument, or automatically create & choose the custom element under ShadowDOM.
+ */
+export declare const useAutomaticTargetDomNode: (providedTargetDomNode?: PortalContextValue, hangingElement?: HTMLElement | null) => HTMLElement;
+export {};