@moneyforward/mfui-components 2.48.1

package/dist/cjs/src/utilities/dom/usePopoverMenuPlacement.js

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usePopoverMenuPlacement = usePopoverMenuPlacement;
+const react_dom_1 = require("@floating-ui/react-dom");
+const useIsNarrowViewport_1 = require("../responsive/useIsNarrowViewport");
+// Mapping from our placement type to Floating UI placement type
+const placementMapping = {
+    top: 'top',
+    'top-start': 'top-start',
+    'top-end': 'top-end',
+    bottom: 'bottom',
+    'bottom-start': 'bottom-start',
+    'bottom-end': 'bottom-end',
+    left: 'left',
+    'left-start': 'left-start',
+    'left-end': 'left-end',
+    right: 'right',
+    'right-start': 'right-start',
+    'right-end': 'right-end',
+};
+/**
+ * Manages the placement of a popover menu relative to a target element and trigger element.
+ *
+ * @param options - Configuration options
+ *
+ * @param options.minWidth - The minimum width of the popover menu. Default is the width of the trigger element.
+ *
+ * @param options.allowedPlacements - The allowed placements for the popover menu. Default is ['bottom-start', 'bottom-end', 'top-start', 'top-end'].
+ *
+ * @param options.enableViewportConstraint - Whether to enable viewport constraint for the popover content. Default is true.
+ */
+function usePopoverMenuPlacement({ minWidth, maxHeight, allowedPlacements, enableViewportConstraint = true, constrainToTriggerWidth = false, enableCenteredLayoutOnNarrowViewport = false, } = {}) {
+    // Detect narrow viewport (< 600px)
+    const isNarrowViewport = (0, useIsNarrowViewport_1.useIsNarrowViewport)();
+    const shouldCenterInViewport = enableCenteredLayoutOnNarrowViewport && isNarrowViewport;
+    const middleware = [
+        /*
+         * autoPlacement allows the menu to be placed in the correct position
+         * @see https://floating-ui.com/docs/autoPlacement
+         *
+         * Skip autoPlacement when centering in viewport, as we'll use custom positioning
+         */
+        !shouldCenterInViewport &&
+            (0, react_dom_1.autoPlacement)({
+                /*
+                 * allowedPlacements specifies the allowed placements for the menu in the order of priority
+                 * @see https://floating-ui.com/docs/autoPlacement#allowedPlacements
+                 */
+                allowedPlacements: allowedPlacements?.map((placement) => placementMapping[placement]) ?? [
+                    'bottom-start',
+                    'bottom-end',
+                    'top-start',
+                    'top-end',
+                ],
+                /*
+                 * When crossAxis is set to true, the middleware evaluates the available space not only along the main axis (e.g., top or bottom) but also along the cross axis (e.g., left or right).
+                 * This ensures that the floating element is placed in the position with the most available space across both axes.
+                 * @see https://floating-ui.com/docs/autoPlacement#crossaxis
+                 */
+                crossAxis: true,
+            }),
+        /*
+         * Custom middleware for centering popover on narrow viewport
+         */
+        shouldCenterInViewport &&
+            {
+                name: 'centerInViewport',
+                fn(state) {
+                    const viewportWidth = window.innerWidth;
+                    const floatingWidth = state.rects.floating.width;
+                    const horizontalMargin = 14; // grid-scale-horizontal-1
+                    // Calculate centered X position with margins
+                    const centeredX = Math.max(horizontalMargin, (viewportWidth - floatingWidth) / 2);
+                    return {
+                        x: centeredX,
+                        y: state.y, // Keep vertical position relative to trigger
+                    };
+                },
+            },
+    ].filter(Boolean);
+    /*
+     * @see https://floating-ui.com/docs/size
+     */
+    if (enableViewportConstraint) {
+        middleware.push((0, react_dom_1.size)({
+            apply({ availableWidth, availableHeight, elements }) {
+                const referenceWidth = elements.reference.getBoundingClientRect().width;
+                const referenceWidthPx = `${String(referenceWidth)}px`;
+                const maxHeightPx = maxHeight ?? `calc(${String(Math.max(0, availableHeight))}px - 12px)`;
+                if (shouldCenterInViewport) {
+                    // Narrow viewport centered layout: maxWidth = viewport - left/right margins (14px each)
+                    const viewportWidth = window.innerWidth;
+                    const horizontalMargin = 14; // grid-scale-horizontal-1
+                    Object.assign(elements.floating.style, {
+                        maxWidth: `${String(viewportWidth - horizontalMargin * 2)}px`,
+                        maxHeight: maxHeightPx,
+                        overflow: 'hidden',
+                        minWidth: 'auto', // Reset minWidth for centered layout
+                    });
+                }
+                else if (constrainToTriggerWidth) {
+                    // When constraining to reference width, both minWidth and maxWidth should match trigger width
+                    Object.assign(elements.floating.style, {
+                        // Vertical padding for Popover height (12px) matching token: padding-main-container-vertical-comfort
+                        maxHeight: maxHeightPx,
+                        // Prevent root element from scrolling; child elements handle overflow
+                        overflow: 'hidden',
+                        // Constrain width to exactly match the trigger element
+                        minWidth: referenceWidthPx,
+                        maxWidth: referenceWidthPx,
+                    });
+                }
+                else {
+                    Object.assign(elements.floating.style, {
+                        // Make the menu to be resized to fit the available space and overflow the menu
+                        // Horizontal padding for Popover width (14px) matching token: padding-main-container-horizontal-comfort
+                        maxWidth: `calc(${String(Math.max(0, availableWidth))}px - 14px)`,
+                        // Vertical padding for Popover height (12px) matching token: padding-main-container-vertical-comfort
+                        maxHeight: maxHeightPx,
+                        // Prevent root element from scrolling; child elements handle overflow
+                        overflow: 'hidden',
+                        // Make the menu to be resized at least to the width of the trigger
+                        minWidth: minWidth ?? referenceWidthPx,
+                    });
+                }
+            },
+        }));
+    }
+    else {
+        // When viewport constraint is disabled, only apply minWidth
+        middleware.push((0, react_dom_1.size)({
+            apply({ elements }) {
+                const referenceWidth = elements.reference.getBoundingClientRect().width;
+                const referenceWidthPx = `${String(referenceWidth)}px`;
+                if (constrainToTriggerWidth) {
+                    // When constraining to reference width, both minWidth and maxWidth should match trigger width
+                    Object.assign(elements.floating.style, {
+                        minWidth: referenceWidthPx,
+                        maxWidth: referenceWidthPx,
+                    });
+                }
+                else {
+                    Object.assign(elements.floating.style, {
+                        // Make the menu to be resized at least to the width of the trigger
+                        minWidth: minWidth ?? referenceWidthPx,
+                    });
+                }
+            },
+        }));
+    }
+    const { refs, floatingStyles, update } = (0, react_dom_1.useFloating)({
+        /*
+         * autoUpdate allows the menu to be updated when the trigger element is moved
+         * @see https://floating-ui.com/docs/autoUpdate#whileElementsMounted
+         */
+        whileElementsMounted: react_dom_1.autoUpdate,
+        middleware,
+    });
+    return { refs, floatingStyles, update };
+}

package/dist/cjs/src/utilities/effect/useUpdateEffect.d.ts

@@ -0,0 +1,14 @@
+import { useEffect } from 'react';
+/**
+ * A hook to call the effect only when the dependencies are updated (not when mounted).
+ * This hook will work in both React non-StrictMode and StrictMode.
+ *
+ * This hook is inspired by this answer on React issue,
+ * where use two useEffect to make sure if it is running on StrictMode or not.
+ * https://github.com/facebook/react/issues/24527
+ *
+ * @param effect - same as useEffect effect
+ *
+ * @param deps - same as useEffect deps
+ */
+export declare const useUpdateEffect: typeof useEffect;

package/dist/cjs/src/utilities/effect/useUpdateEffect.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useUpdateEffect = void 0;
+const react_1 = require("react");
+/**
+ * A hook to call the effect only when the dependencies are updated (not when mounted).
+ * This hook will work in both React non-StrictMode and StrictMode.
+ *
+ * This hook is inspired by this answer on React issue,
+ * where use two useEffect to make sure if it is running on StrictMode or not.
+ * https://github.com/facebook/react/issues/24527
+ *
+ * @param effect - same as useEffect effect
+ *
+ * @param deps - same as useEffect deps
+ */
+const useUpdateEffect = (effect, deps) => {
+    const isMounted = (0, react_1.useRef)(false);
+    (0, react_1.useEffect)(() => {
+        isMounted.current = false;
+    }, []);
+    (0, react_1.useEffect)(() => {
+        if (!isMounted.current) {
+            isMounted.current = true;
+        }
+        else {
+            return effect();
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, deps);
+};
+exports.useUpdateEffect = useUpdateEffect;

package/dist/cjs/src/utilities/pandacss/index.d.ts

@@ -0,0 +1,11 @@
+import type * as Panda from '@pandacss/dev';
+import { type SlotRecipeConfig, type SlotRecipeVariantRecord } from '../../../styled-system/types';
+/**
+ * A wrapper for `defineSlotRecipe` that allows IDEs & Editors to read the type.
+ * Because we are not sure why IDEs & Editors didn't read the types in the `styled-system/types` files.
+ *
+ * @param config - The slot recipe config.
+ *
+ * @returns The slot recipe config.
+ */
+export declare const mfuiDefineSlotRecipe: <S extends string, V extends SlotRecipeVariantRecord<S>>(config: SlotRecipeConfig<S, V>) => Panda.SlotRecipeConfig;

package/dist/cjs/src/utilities/pandacss/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mfuiDefineSlotRecipe = void 0;
+const dev_1 = require("@pandacss/dev");
+/**
+ * A wrapper for `defineSlotRecipe` that allows IDEs & Editors to read the type.
+ * Because we are not sure why IDEs & Editors didn't read the types in the `styled-system/types` files.
+ *
+ * @param config - The slot recipe config.
+ *
+ * @returns The slot recipe config.
+ */
+exports.mfuiDefineSlotRecipe = dev_1.defineSlotRecipe;

package/dist/cjs/src/utilities/react/compatibleForwardRef.d.ts

@@ -0,0 +1,17 @@
+import { type Attributes, type ForwardRefExoticComponent, type ForwardRefRenderFunction, type PropsWithoutRef, type RefCallback, type RefObject } from 'react';
+/**
+ * From React 19+, The `Ref<T>` type include `RefObject<T | null>` instead of `RefObject<T>`,
+ * which make some of our components/hooks incompatible with React 18.
+ *
+ * @see https://react.dev/blog/2024/04/25/react-19-upgrade-guide#useref-requires-argument
+ */
+type CompatibleRef<T> = RefCallback<T> | RefObject<T | null> | null;
+type CompatibleRefAttributes<T> = {
+    ref?: CompatibleRef<T> | undefined;
+} & Attributes;
+type CompatibleForwardRef = <T, P = object>(render: ForwardRefRenderFunction<T, PropsWithoutRef<P>>) => ForwardRefExoticComponent<PropsWithoutRef<P> & CompatibleRefAttributes<T>>;
+/**
+ * A forwardRef function that is compatible with both React 18 and 19+.
+ */
+export declare const compatibleForwardRef: CompatibleForwardRef;
+export {};

package/dist/cjs/src/utilities/react/compatibleForwardRef.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compatibleForwardRef = void 0;
+const react_1 = require("react");
+/**
+ * A forwardRef function that is compatible with both React 18 and 19+.
+ */
+exports.compatibleForwardRef = react_1.forwardRef;

package/dist/cjs/src/utilities/react/isComponentOrWrapped.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Checks if a React element is of a specific component type or wraps that component.
+ *
+ * This utility is useful when you need to identify components in `Children.map` or similar scenarios,
+ * especially when components use composition patterns.
+ *
+ * **Detection Strategy (Hybrid Approach):**
+ * 1. **Direct type matching** - Fast and reliable
+ * 2. **displayName matching** - Recommended for wrapper components (avoids hooks violations)
+ * 3. **Fallback rendering** - For backward compatibility with simple wrappers without displayName
+ * 4. **Graceful failure** - If rendering throws (e.g., hooks error), returns false
+ *
+ * **Best Practice**: Set `displayName` on wrapper components to match the target component's `displayName`.
+ * This is especially important for wrappers that use React hooks, as rendering them outside of
+ * React's component lifecycle will cause errors.
+ *
+ * @param element - The React element to check
+ *
+ * @param targetComponent - The component type to check against
+ *
+ * @returns `true` if the element is the target component or wraps it, `false` otherwise
+ *
+ * @example
+ *
+ * ```tsx
+ * // Direct usage
+ * if (isComponentOrWrapped(child, MyComponent)) {
+ *   // child is MyComponent or wraps MyComponent
+ * }
+ *
+ * // In Children.map
+ * Children.map(children, (child) => {
+ *   if (!isValidElement(child)) return child;
+ *   if (isComponentOrWrapped(child, DataGridCell)) {
+ *     return cloneElement(child, { ...additionalProps });
+ *   }
+ *   return child;
+ * });
+ *
+ * // Creating a wrapper component (recommended approach)
+ * const WrappedDataGridCell = (props) => {
+ *   return <DataGridCell {...props} customProp="value" />;
+ * };
+ * WrappedDataGridCell.displayName = 'DataGridCell'; // Recommended for detection
+ *
+ * // Wrapper with hooks (displayName is required)
+ * const WrappedDataGridCellWithHooks = (props) => {
+ *   const [state, setState] = useState(initialState);
+ *   return <DataGridCell {...props} state={state} />;
+ * };
+ * WrappedDataGridCellWithHooks.displayName = 'DataGridCell'; // Required to avoid hooks error
+ * ```
+ */
+export declare function isComponentOrWrapped<P = unknown>(element: React.ReactElement, targetComponent: React.ComponentType<P>): boolean;

package/dist/cjs/src/utilities/react/isComponentOrWrapped.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isComponentOrWrapped = isComponentOrWrapped;
+const react_1 = require("react");
+/**
+ * Checks if a React element is of a specific component type or wraps that component.
+ *
+ * This utility is useful when you need to identify components in `Children.map` or similar scenarios,
+ * especially when components use composition patterns.
+ *
+ * **Detection Strategy (Hybrid Approach):**
+ * 1. **Direct type matching** - Fast and reliable
+ * 2. **displayName matching** - Recommended for wrapper components (avoids hooks violations)
+ * 3. **Fallback rendering** - For backward compatibility with simple wrappers without displayName
+ * 4. **Graceful failure** - If rendering throws (e.g., hooks error), returns false
+ *
+ * **Best Practice**: Set `displayName` on wrapper components to match the target component's `displayName`.
+ * This is especially important for wrappers that use React hooks, as rendering them outside of
+ * React's component lifecycle will cause errors.
+ *
+ * @param element - The React element to check
+ *
+ * @param targetComponent - The component type to check against
+ *
+ * @returns `true` if the element is the target component or wraps it, `false` otherwise
+ *
+ * @example
+ *
+ * ```tsx
+ * // Direct usage
+ * if (isComponentOrWrapped(child, MyComponent)) {
+ *   // child is MyComponent or wraps MyComponent
+ * }
+ *
+ * // In Children.map
+ * Children.map(children, (child) => {
+ *   if (!isValidElement(child)) return child;
+ *   if (isComponentOrWrapped(child, DataGridCell)) {
+ *     return cloneElement(child, { ...additionalProps });
+ *   }
+ *   return child;
+ * });
+ *
+ * // Creating a wrapper component (recommended approach)
+ * const WrappedDataGridCell = (props) => {
+ *   return <DataGridCell {...props} customProp="value" />;
+ * };
+ * WrappedDataGridCell.displayName = 'DataGridCell'; // Recommended for detection
+ *
+ * // Wrapper with hooks (displayName is required)
+ * const WrappedDataGridCellWithHooks = (props) => {
+ *   const [state, setState] = useState(initialState);
+ *   return <DataGridCell {...props} state={state} />;
+ * };
+ * WrappedDataGridCellWithHooks.displayName = 'DataGridCell'; // Required to avoid hooks error
+ * ```
+ */
+function isComponentOrWrapped(element, targetComponent) {
+    if (!(0, react_1.isValidElement)(element))
+        return false;
+    // 1. Direct type check - fastest path
+    if (element.type === targetComponent)
+        return true;
+    // 2. displayName check (primary method - safe, no hooks violations)
+    const targetDisplayName = targetComponent.displayName;
+    const elementDisplayName = typeof element.type === 'function' || typeof element.type === 'object'
+        ? element.type.displayName
+        : undefined;
+    if (targetDisplayName && elementDisplayName && elementDisplayName === targetDisplayName) {
+        return true;
+    }
+    // 3. Fallback: Try rendering (backward compatibility for simple wrappers without displayName)
+    // Only attempt this for function components (not class components)
+    if (typeof element.type === 'function') {
+        // Check if it's a class component by looking for prototype.isReactComponent
+        const isClassComponent = 'prototype' in element.type &&
+            element.type.prototype !== null &&
+            typeof element.type.prototype === 'object' &&
+            'isReactComponent' in element.type.prototype;
+        if (!isClassComponent) {
+            try {
+                const result = element.type(element.props);
+                if ((0, react_1.isValidElement)(result) && result.type === targetComponent) {
+                    // Warn in development about better practice
+                    if (process.env['NODE_ENV'] !== 'production' && targetDisplayName) {
+                        console.warn(`[MFUI] Wrapper component detected without displayName. ` +
+                            `This may cause issues if your wrapper uses React hooks. ` +
+                            `Please set displayName="${targetDisplayName}" on your wrapper component.`);
+                    }
+                    return true;
+                }
+            }
+            catch {
+                // Rendering failed (likely hooks error) - wrapper not detectable
+                // This is expected for wrappers with hooks that don't set displayName
+                return false;
+            }
+        }
+    }
+    return false;
+}

package/dist/cjs/src/utilities/responsive/index.d.ts

@@ -0,0 +1,15 @@
+import { type ReactNode } from 'react';
+import { type ResponsiveSlot } from '../../types/responsive';
+/**
+ * Generic type guard function to check if a value is a ResponsiveSlot-like object.
+ * This function checks for the structural pattern of having 'base' and optionally 'narrowViewport' properties,
+ * making it compatible with both ResponsiveSlot and other similar responsive slot types.
+ *
+ * @param value - The value to check
+ *
+ * @returns true if the value has the ResponsiveSlot structure, false otherwise
+ */
+export declare const isResponsiveSlot: <TSlot extends {
+    base: unknown;
+    narrowViewport?: unknown;
+} = ResponsiveSlot>(value: TSlot | ReactNode | ((...args: any[]) => ReactNode)) => value is TSlot;

package/dist/cjs/src/utilities/responsive/index.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isResponsiveSlot = void 0;
+/**
+ * Generic type guard function to check if a value is a ResponsiveSlot-like object.
+ * This function checks for the structural pattern of having 'base' and optionally 'narrowViewport' properties,
+ * making it compatible with both ResponsiveSlot and other similar responsive slot types.
+ *
+ * @param value - The value to check
+ *
+ * @returns true if the value has the ResponsiveSlot structure, false otherwise
+ */
+const isResponsiveSlot = (value) => {
+    if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    // Check if it's a React element (has $$typeof property)
+    if ('$$typeof' in value) {
+        return false;
+    }
+    // Check if it has the exact structure of ResponsiveSlot
+    const object = value;
+    return 'base' in object && Object.keys(object).every((key) => key === 'base' || key === 'narrowViewport');
+};
+exports.isResponsiveSlot = isResponsiveSlot;

package/dist/cjs/src/utilities/responsive/useIsNarrowViewport.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Hook to detect if the current viewport is narrow (below specified breakpoint).
+ * Uses the same pattern as ToastContainer with window.innerWidth and resize event.
+ *
+ * According to MFUI Guidelines (Screen Layout and Patterns - Responsive and Breakpoints):
+ * - Wide layout components (e.g., GlobalHeader): 1200px breakpoint
+ * - Other mobile-responsive components: 600px breakpoint (sm breakpoint in panda.config.ts)
+ *
+ * @param breakpoint - The breakpoint width in pixels. Default is 600px (sm breakpoint).
+ *                     Use 1200px for wide layout components like GlobalHeader.
+ *
+ * @returns true if the viewport width is less than the breakpoint, false otherwise
+ *
+ * @example
+ * ```tsx
+ * // Default 600px breakpoint (most mobile components)
+ * function MyComponent() {
+ *   const isNarrow = useIsNarrowViewport();
+ *
+ *   return (
+ *     <div>
+ *       {isNarrow ? 'Narrow Viewport' : 'Wide Viewport'}
+ *     </div>
+ *   );
+ * }
+ *
+ * // 1200px breakpoint (GlobalHeader, wide layout components)
+ * function WideLayoutComponent() {
+ *   const isNarrow = useIsNarrowViewport(1200);
+ *
+ *   return (
+ *     <div>
+ *       {isNarrow ? 'Below 1200px' : 'Above 1200px'}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare const useIsNarrowViewport: (breakpoint?: number) => boolean;

package/dist/cjs/src/utilities/responsive/useIsNarrowViewport.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useIsNarrowViewport = void 0;
+const react_1 = require("react");
+/**
+ * Hook to detect if the current viewport is narrow (below specified breakpoint).
+ * Uses the same pattern as ToastContainer with window.innerWidth and resize event.
+ *
+ * According to MFUI Guidelines (Screen Layout and Patterns - Responsive and Breakpoints):
+ * - Wide layout components (e.g., GlobalHeader): 1200px breakpoint
+ * - Other mobile-responsive components: 600px breakpoint (sm breakpoint in panda.config.ts)
+ *
+ * @param breakpoint - The breakpoint width in pixels. Default is 600px (sm breakpoint).
+ *                     Use 1200px for wide layout components like GlobalHeader.
+ *
+ * @returns true if the viewport width is less than the breakpoint, false otherwise
+ *
+ * @example
+ * ```tsx
+ * // Default 600px breakpoint (most mobile components)
+ * function MyComponent() {
+ *   const isNarrow = useIsNarrowViewport();
+ *
+ *   return (
+ *     <div>
+ *       {isNarrow ? 'Narrow Viewport' : 'Wide Viewport'}
+ *     </div>
+ *   );
+ * }
+ *
+ * // 1200px breakpoint (GlobalHeader, wide layout components)
+ * function WideLayoutComponent() {
+ *   const isNarrow = useIsNarrowViewport(1200);
+ *
+ *   return (
+ *     <div>
+ *       {isNarrow ? 'Below 1200px' : 'Above 1200px'}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+const useIsNarrowViewport = (breakpoint = 600) => {
+    const [isNarrow, setIsNarrow] = (0, react_1.useState)(false);
+    (0, react_1.useLayoutEffect)(() => {
+        const checkViewportWidth = () => {
+            setIsNarrow(window.innerWidth < breakpoint);
+        };
+        // Check on mount
+        checkViewportWidth();
+        // Add resize listener
+        window.addEventListener('resize', checkViewportWidth);
+        return () => {
+            window.removeEventListener('resize', checkViewportWidth);
+        };
+    }, [breakpoint]);
+    return isNarrow;
+};
+exports.useIsNarrowViewport = useIsNarrowViewport;

package/dist/cjs/src/utilities/state/useDisclosure.d.ts

@@ -0,0 +1,41 @@
+type UseDisclosureProps = {
+    /**
+     * The initial open state.
+     */
+    value?: boolean;
+    /**
+     * Callback when the option panel is opened.
+     */
+    onOpen?: () => void;
+    /**
+     * Callback when the option panel is closed.
+     */
+    onClose?: () => void;
+    /**
+     * Callback when the option panel is toggled.
+     *
+     * @param nextValue - The next open state.
+     */
+    onToggle?: (nextValue: boolean) => void;
+};
+/**
+ * Custom hook to manage the disclosure state.
+ * Use this only inside the client component.
+ *
+ * @property isOpen - Indicates whether the option panel is open
+ *
+ * @property  toggle - Function to toggle the option panel open/closed state
+ *
+ * @property  open - Function to open the option panel
+ *
+ * @property  close - Function to close the option panel
+ *
+ * @returns  The list box state and control functions
+ */
+export declare const useDisclosure: ({ value, onOpen, onClose, onToggle }?: UseDisclosureProps) => {
+    isOpen: boolean;
+    toggle: () => void;
+    open: () => void;
+    close: () => void;
+};
+export {};

package/dist/cjs/src/utilities/state/useDisclosure.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useDisclosure = void 0;
+const react_1 = require("react");
+const useUpdateEffect_1 = require("../effect/useUpdateEffect");
+/**
+ * Custom hook to manage the disclosure state.
+ * Use this only inside the client component.
+ *
+ * @property isOpen - Indicates whether the option panel is open
+ *
+ * @property  toggle - Function to toggle the option panel open/closed state
+ *
+ * @property  open - Function to open the option panel
+ *
+ * @property  close - Function to close the option panel
+ *
+ * @returns  The list box state and control functions
+ */
+const useDisclosure = ({ value = false, onOpen, onClose, onToggle } = {}) => {
+    const [isOpen, setIsOpen] = (0, react_1.useState)(value);
+    (0, useUpdateEffect_1.useUpdateEffect)(() => {
+        setIsOpen(value);
+    }, [value]);
+    const toggle = (0, react_1.useCallback)(() => {
+        setIsOpen(!isOpen);
+        onToggle?.(!isOpen);
+    }, [onToggle, isOpen]);
+    const open = (0, react_1.useCallback)(() => {
+        setIsOpen(true);
+        onOpen?.();
+    }, [onOpen]);
+    const close = (0, react_1.useCallback)(() => {
+        setIsOpen(false);
+        onClose?.();
+    }, [onClose]);
+    return {
+        isOpen,
+        toggle,
+        open,
+        close,
+    };
+};
+exports.useDisclosure = useDisclosure;