@moneyforward/mfui-components 2.48.1

package/dist/esm/src/SelectBox/hooks/useVirtualizedOptions.d.ts

@@ -0,0 +1,63 @@
+import { useVirtualizer } from '@tanstack/react-virtual';
+import { type RefObject } from 'react';
+import { type BasedAdditionalProps, type FlatOption, type VirtualOptionTypes } from '../SelectBox.types';
+export type UseVirtualizedOptionsParams<T extends string | number | undefined = string, AdditionalProps extends BasedAdditionalProps = BasedAdditionalProps> = {
+    /**
+     * Enable virtualization for the option list
+     */
+    enabled: boolean;
+    /**
+     * Reference to the scrollable parent element
+     */
+    parentRef: RefObject<HTMLElement | null>;
+    /**
+     * Flat array of all options
+     */
+    flatOptions: FlatOption<T, AdditionalProps>[];
+} & Partial<VirtualOptionTypes>;
+export type UseVirtualizedOptionsReturn = {
+    /**
+     * The virtualizer instance from @tanstack/react-virtual
+     * Null when virtualization is disabled
+     */
+    virtualizer: ReturnType<typeof useVirtualizer<HTMLElement, Element>> | null;
+    /**
+     * Array of virtual items to render (only visible + overscan items)
+     */
+    virtualItems: ReturnType<typeof useVirtualizer<HTMLElement, Element>>['getVirtualItems'] extends () => infer R ? R : never;
+    /**
+     * Total height of all items combined
+     */
+    totalSize: number;
+    /**
+     * Scroll to a specific option by index
+     */
+    scrollToIndex: (index: number, options?: {
+        align?: 'start' | 'center' | 'end' | 'auto';
+        behavior?: 'auto' | 'smooth';
+    }) => void;
+    /**
+     * Whether virtualization is currently enabled
+     */
+    isVirtualized: boolean;
+};
+/**
+ * Custom hook for virtualizing large option lists using @tanstack/react-virtual.
+ * Only renders visible items + overscan for improved performance.
+ *
+ * @param params - Virtualization configuration
+ *
+ * @returns Virtualizer instance and helper methods
+ *
+ * @example
+ * ```tsx
+ * const { virtualItems, totalSize, scrollToIndex, isVirtualized } = useVirtualizedOptions({
+ *   enabled: true,
+ *   parentRef: optionPanelRef,
+ *   flatOptions,
+ *   estimateSize: () => 36, // or (index) => index < 10 ? 40 : 36 for dynamic sizing
+ *   overscan: 5,
+ * });
+ * ```
+ */
+export declare function useVirtualizedOptions<T extends string | number | undefined = string, AdditionalProps extends BasedAdditionalProps = BasedAdditionalProps>({ enabled, parentRef, flatOptions, estimateSize, overscan, }: UseVirtualizedOptionsParams<T, AdditionalProps>): UseVirtualizedOptionsReturn;

package/dist/esm/src/SelectBox/hooks/useVirtualizedOptions.js

@@ -0,0 +1,54 @@
+import { useVirtualizer } from '@tanstack/react-virtual';
+import { useCallback } from 'react';
+/**
+ * Custom hook for virtualizing large option lists using @tanstack/react-virtual.
+ * Only renders visible items + overscan for improved performance.
+ *
+ * @param params - Virtualization configuration
+ *
+ * @returns Virtualizer instance and helper methods
+ *
+ * @example
+ * ```tsx
+ * const { virtualItems, totalSize, scrollToIndex, isVirtualized } = useVirtualizedOptions({
+ *   enabled: true,
+ *   parentRef: optionPanelRef,
+ *   flatOptions,
+ *   estimateSize: () => 36, // or (index) => index < 10 ? 40 : 36 for dynamic sizing
+ *   overscan: 5,
+ * });
+ * ```
+ */
+export function useVirtualizedOptions({ enabled, parentRef, flatOptions, estimateSize = () => 36, overscan = 5, }) {
+    // Always call useVirtualizer to maintain hook order, but with 0 count when disabled
+    const virtualizer = useVirtualizer({
+        count: enabled ? flatOptions.length : 0,
+        getScrollElement: () => 
+        // parentRef points to scrollWrapper, which is always the scroll container
+        // Structure: Popover root > optionPanel > scrollWrapper (parentRef) > listBox
+        parentRef.current ?? null,
+        estimateSize,
+        overscan,
+        enabled,
+    });
+    const scrollToIndex = useCallback((index, options) => {
+        if (!enabled)
+            return;
+        // Safety check: ensure index is within bounds
+        const { count } = virtualizer.options;
+        if (index < 0 || index >= count)
+            return;
+        virtualizer.scrollToIndex(index, {
+            align: 'center',
+            behavior: 'auto',
+            ...options,
+        });
+    }, [enabled, virtualizer]);
+    return {
+        virtualizer: enabled ? virtualizer : null,
+        virtualItems: enabled ? virtualizer.getVirtualItems() : [],
+        totalSize: enabled ? virtualizer.getTotalSize() : 0,
+        scrollToIndex,
+        isVirtualized: enabled,
+    };
+}

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

@@ -0,0 +1,2 @@
+export { SelectBox } from './SelectBox';
+export type { SelectBoxProps, SelectBoxOption } from './SelectBox.types';

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

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

package/dist/esm/src/SelectBox/utils/findFlatOptionIndexByValue.d.ts

@@ -0,0 +1,18 @@
+import { type BasedAdditionalProps, type SelectBoxOption } from '../SelectBox.types';
+/**
+ * Builds a Map from option value to its index in flatOptions for O(1) lookup.
+ *
+ * @param flatOptions - The array of flat options to index.
+ *
+ * @returns Map of value to index.
+ */
+export declare function buildValueToIndexMap<T extends string | number | undefined = string, AdditionalProps extends BasedAdditionalProps = BasedAdditionalProps>(flatOptions: SelectBoxOption<T, AdditionalProps>[]): Map<string | number, number>;
+/**
+ * Finds the index of an option in flatOptions by matching the value property using a prebuilt map.
+ * Returns -1 if not found or if the option has no value.
+ *
+ * @param valueToIndexMap - Map from value to index, built from flatOptions.
+ *
+ * @param option - The option whose value to match.
+ */
+export declare function findFlatOptionIndexByValue<T extends string | number | undefined = string, AdditionalProps extends BasedAdditionalProps = BasedAdditionalProps>(valueToIndexMap: Map<string | number, number>, option: SelectBoxOption<T, AdditionalProps>): number;

package/dist/esm/src/SelectBox/utils/findFlatOptionIndexByValue.js

@@ -0,0 +1,29 @@
+/**
+ * Builds a Map from option value to its index in flatOptions for O(1) lookup.
+ *
+ * @param flatOptions - The array of flat options to index.
+ *
+ * @returns Map of value to index.
+ */
+export function buildValueToIndexMap(flatOptions) {
+    const map = new Map();
+    flatOptions.forEach((option, index) => {
+        if ('value' in option && option.value !== undefined) {
+            map.set(option.value, index);
+        }
+    });
+    return map;
+}
+/**
+ * Finds the index of an option in flatOptions by matching the value property using a prebuilt map.
+ * Returns -1 if not found or if the option has no value.
+ *
+ * @param valueToIndexMap - Map from value to index, built from flatOptions.
+ *
+ * @param option - The option whose value to match.
+ */
+export function findFlatOptionIndexByValue(valueToIndexMap, option) {
+    if (!('value' in option) || option.value === undefined)
+        return -1;
+    return valueToIndexMap.get(option.value) ?? -1;
+}

package/dist/esm/src/SelectBox/utils/findOptionByValue.d.ts

@@ -0,0 +1,11 @@
+import { type BasedAdditionalProps, type SelectBoxOption } from '../SelectBox.types';
+/**
+ * Finds an option in a (potentially) nested SelectBox options array by its value.
+ *
+ * @param options - The (possibly nested) options array to search in.
+ *
+ * @param value - The value to search for.
+ *
+ * @returns The found option or null if no option with the given value exists.
+ */
+export declare function findOptionByValue<T extends string | number | undefined = string, AdditionalProps extends BasedAdditionalProps = BasedAdditionalProps>(options: (SelectBoxOption<T, AdditionalProps> | null | undefined)[], value: T | undefined): SelectBoxOption<T, AdditionalProps> | null;

package/dist/esm/src/SelectBox/utils/findOptionByValue.js

@@ -0,0 +1,25 @@
+/**
+ * Finds an option in a (potentially) nested SelectBox options array by its value.
+ *
+ * @param options - The (possibly nested) options array to search in.
+ *
+ * @param value - The value to search for.
+ *
+ * @returns The found option or null if no option with the given value exists.
+ */
+export function findOptionByValue(options, value) {
+    for (const option of options) {
+        if (!option) {
+            // Skip null or undefined options
+        }
+        else if ('options' in option && Array.isArray(option.options)) {
+            const found = option.options.find((opt) => opt.value === value);
+            if (found)
+                return found;
+        }
+        else if (option.value === value) {
+            return option;
+        }
+    }
+    return null;
+}

package/dist/esm/src/SelectBox/utils/getFlatOptions.d.ts

@@ -0,0 +1,28 @@
+import { type BasedAdditionalProps, type SelectBoxOption } from '../SelectBox.types';
+/**
+ * Flattens a (potentially) nested SelectBox options array into a single–level array of selectable options.
+ *
+ * Group options (objects that contain an `options` property) are traversed and their selectable child options are
+ * collected. Only options that satisfy `isSelectableOption` (i.e. have a `value`) are included in the resulting
+ * array.
+ *
+ * This utility is primarily used to simplify focus-management and keyboard-navigation logic inside the SelectBox
+ * component.
+ *
+ * @param options - The (possibly nested) options array.
+ *
+ * @returns A flat array that contains only selectable options in the same order they appear visually.
+ */
+export declare function getFlatOptions<T extends string | number | undefined = string, AdditionalProps extends BasedAdditionalProps = BasedAdditionalProps>(options: (SelectBoxOption<T, AdditionalProps> | null | undefined)[]): Extract<SelectBoxOption<T, AdditionalProps>, {
+    value?: T;
+}>[];
+/**
+ * Escapes a string or number for use as a CSS attribute value selector.
+ * Uses CSS.escape if available, otherwise falls back to a polyfill.
+ * See: https://mathiasbynens.be/notes/css-escapes
+ *
+ * @param value - The value to escape for use in a CSS selector
+ *
+ * @returns The escaped string
+ */
+export declare function escapeAttributeSelector(value: string | number): string;

package/dist/esm/src/SelectBox/utils/getFlatOptions.js

@@ -0,0 +1,53 @@
+import { isSelectableOption } from './isSelectableOption';
+/**
+ * Flattens a (potentially) nested SelectBox options array into a single–level array of selectable options.
+ *
+ * Group options (objects that contain an `options` property) are traversed and their selectable child options are
+ * collected. Only options that satisfy `isSelectableOption` (i.e. have a `value`) are included in the resulting
+ * array.
+ *
+ * This utility is primarily used to simplify focus-management and keyboard-navigation logic inside the SelectBox
+ * component.
+ *
+ * @param options - The (possibly nested) options array.
+ *
+ * @returns A flat array that contains only selectable options in the same order they appear visually.
+ */
+export function getFlatOptions(options) {
+    return options.flatMap((option) => {
+        if (option && 'options' in option && Array.isArray(option.options)) {
+            return option.options.filter(isSelectableOption);
+        }
+        if (option && isSelectableOption(option)) {
+            return [option];
+        }
+        return [];
+    });
+}
+/**
+ * Escapes a string or number for use as a CSS attribute value selector.
+ * Uses CSS.escape if available, otherwise falls back to a polyfill.
+ * See: https://mathiasbynens.be/notes/css-escapes
+ *
+ * @param value - The value to escape for use in a CSS selector
+ *
+ * @returns The escaped string
+ */
+export function escapeAttributeSelector(value) {
+    const stringValue = String(value);
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (typeof window !== 'undefined' && window.CSS && typeof window.CSS.escape === 'function') {
+        return window.CSS.escape(stringValue);
+    }
+    // Polyfill for CSS.escape
+    // https://github.com/mathiasbynens/CSS.escape
+    function escapeChar(c) {
+        const code = c.codePointAt(0);
+        const hex = code !== undefined ? code.toString(16).toUpperCase() : '';
+        if (!hex)
+            return '';
+        return `\\${hex} `;
+    }
+    // eslint-disable-next-line unicorn/prefer-string-replace-all
+    return stringValue.replace(/[^a-zA-Z0-9\u00A0-\u10FFFF_-]/g, escapeChar);
+}

package/dist/esm/src/SelectBox/utils/isSelectableOption.d.ts

@@ -0,0 +1,17 @@
+import { type BasedAdditionalProps, type SelectBoxOption } from '../SelectBox.types';
+/**
+ * Type guard to check if an option is a selectable option (has value and may have disabled)
+ *
+ * @param option - The option to check
+ *
+ * @returns True if the option has a value (is not a group label)
+ */
+export declare function isSelectableOption<T extends string | number | undefined = string, AdditionalProps extends BasedAdditionalProps = BasedAdditionalProps>(option: SelectBoxOption<T, AdditionalProps>): option is Extract<SelectBoxOption<T, AdditionalProps>, {
+    value?: T;
+}>;
+/**
+ * Returns true if the option is selectable and disabled.
+ *
+ * @param option - Option to check
+ */
+export declare function isOptionDisabled<T extends string | number | undefined = string, AdditionalProps extends BasedAdditionalProps = BasedAdditionalProps>(option: SelectBoxOption<T, AdditionalProps>): boolean;

package/dist/esm/src/SelectBox/utils/isSelectableOption.js

@@ -0,0 +1,18 @@
+/**
+ * Type guard to check if an option is a selectable option (has value and may have disabled)
+ *
+ * @param option - The option to check
+ *
+ * @returns True if the option has a value (is not a group label)
+ */
+export function isSelectableOption(option) {
+    return 'value' in option;
+}
+/**
+ * Returns true if the option is selectable and disabled.
+ *
+ * @param option - Option to check
+ */
+export function isOptionDisabled(option) {
+    return isSelectableOption(option) && 'disabled' in option && !!option.disabled;
+}

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

@@ -0,0 +1,27 @@
+/**
+ * The general purpose SidePane component.
+ * This component extends the props of `<div>` element with `role="dialog"`.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog
+ */
+export declare const SidePane: import("react").ForwardRefExoticComponent<{
+    children?: import("react").ReactNode;
+    title?: string;
+    renderHeading?: (options: import("./SidePane.types").SidePaneRenderOptions) => import("react").ReactNode;
+    actionSlot?: import("react").ReactNode;
+    position?: import("../../styled-system/recipes").SidePaneSlotRecipeVariant["position"];
+    closeButtonProps?: {
+        isCollapseIcon?: boolean;
+    } & Pick<import("react").ComponentPropsWithoutRef<"button">, "aria-label">;
+    targetDOMNode?: HTMLElement | null;
+    enableModal?: boolean;
+    disableBackdropClose?: boolean;
+    enableAutoUnmount?: boolean;
+    insideProps?: {
+        className?: string;
+    };
+    open?: boolean;
+    onClose?: import("./SidePane.types").OnCloseFunction;
+} & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "open" | "onClose"> & {
+    ref?: (import("react").RefObject<HTMLDivElement | null> | import("react").RefCallback<HTMLDivElement | null> | null) | undefined;
+} & import("react").Attributes>;

package/dist/esm/src/SidePane/SidePane.js

@@ -0,0 +1,61 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useMemo } from 'react';
+import { Close, PaneExpansionToRight, PaneExpansionToLeft } from '@moneyforward/mfui-icons-react';
+import { cx } from '../../styled-system/css';
+import { Heading } from '../Heading';
+import { IconButton } from '../IconButton';
+import { sidePaneSlotRecipe } from '../../styled-system/recipes';
+import { useSidePaneStateController } from './hooks/useSidePaneStateController';
+import { useFocusTrap } from '../utilities/dom/useFocusTrap';
+import { compatibleForwardRef } from '../utilities/react/compatibleForwardRef';
+import { Portal, TargetDomNodeProvider, useAutomaticTargetDomNode } from '../Portal';
+/**
+ * The general purpose SidePane component.
+ * This component extends the props of `<div>` element with `role="dialog"`.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog
+ */
+export const SidePane = compatibleForwardRef(({ open, title, renderHeading, onClose, className, children, actionSlot, position = 'right', enableModal = false, enableAutoUnmount = true, disableBackdropClose = false, closeButtonProps, targetDOMNode, insideProps, ...props }, ref) => {
+    const classes = sidePaneSlotRecipe({ position, nonModal: !enableModal });
+    const { localOpen, handleCloseSidePane, handleStopCloseSidePane, sidePaneElement, setSidePaneElement } = useSidePaneStateController({
+        open,
+        onClose,
+        ref,
+    });
+    const handleBackdropClick = useCallback(() => {
+        if (!disableBackdropClose) {
+            handleCloseSidePane();
+        }
+    }, [disableBackdropClose, handleCloseSidePane]);
+    const handleKeyDown = useCallback((event) => {
+        if (event.key === 'Escape') {
+            event.stopPropagation();
+            event.preventDefault();
+            handleCloseSidePane();
+        }
+        props.onKeyDown?.(event);
+    }, [handleCloseSidePane, props]);
+    // Get the focus trap handler
+    const { handleOnKeyDown: focusTrapKeyHandler } = useFocusTrap({
+        onKeyDown: handleKeyDown,
+    });
+    // Only use focus trap for modal SidePanes
+    const handleOnKeyDown = enableModal ? focusTrapKeyHandler : handleKeyDown;
+    const closeButtonIcon = useMemo(() => {
+        if (!closeButtonProps?.isCollapseIcon) {
+            return _jsx(Close, {});
+        }
+        if (position === 'left') {
+            return _jsx(PaneExpansionToLeft, {});
+        }
+        return _jsx(PaneExpansionToRight, {});
+    }, [closeButtonProps?.isCollapseIcon, position]);
+    const targetElement = useAutomaticTargetDomNode(targetDOMNode, sidePaneElement);
+    const shouldRenderContent = enableAutoUnmount ? localOpen : true;
+    const headingNode = title ? (_jsx(Heading, { variant: "pageHeading2", tag: "h2", children: title })) : null;
+    return (_jsx(TargetDomNodeProvider, { targetDomNode: sidePaneElement, children: shouldRenderContent ? (_jsx(Portal, { targetDOMNode: targetElement, children: _jsxs("div", { ref: setSidePaneElement, role: "dialog", ...props, className: cx(classes.root, 'mfui-SidePane__root', className), tabIndex: -1, style: {
+                    ...props.style,
+                    ...(!enableAutoUnmount && !localOpen && { display: 'none' }),
+                }, onKeyDown: handleOnKeyDown, children: [enableModal ? (_jsx("div", { "data-mfui-content": "backdrop", className: cx(classes.backdrop, 'mfui-SidePane__backdrop'), onClick: handleBackdropClick })) : null, _jsxs("div", { "data-mfui-content": "inside", className: cx(classes.inside, 'mfui-SidePane__inside', insideProps?.className), onClick: handleStopCloseSidePane, children: [_jsxs("header", { className: cx(classes.header, 'mfui-SidePane__header'), children: [renderHeading ? (renderHeading({ headingNode })) : (_jsx("div", { className: cx(classes.title, 'mfui-SidePane__title'), children: headingNode })), _jsxs("div", { className: cx(classes.actionSlotWrapper, 'mfui-SidePane__actionSlotWrapper'), children: [!!actionSlot && (_jsx("div", { className: cx(classes.actionSlot, 'mfui-SidePane__actionSlot'), children: actionSlot })), _jsx("div", { className: cx(classes.closeButtonWrapper, 'mfui-SidePane__closeButtonWrapper'), children: _jsx(IconButton, { "aria-label": closeButtonProps?.['aria-label'] ?? '閉じる', onClick: handleCloseSidePane, children: closeButtonIcon }) })] })] }), _jsx("main", { className: cx(classes.content, 'mfui-SidePane__content'), children: children })] })] }) })) : null }));
+});

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

@@ -0,0 +1,134 @@
+import { type ComponentPropsWithoutRef, type ReactNode } from 'react';
+import { type SidePaneSlotRecipeVariant } from '../../styled-system/recipes';
+export type OnCloseFunction = () => void;
+export type SidePaneRenderOptions = {
+    /**
+     * The original heading element wrapped in <h2> tag.
+     * This ensures proper semantic HTML structure and accessibility.
+     */
+    headingNode: ReactNode;
+};
+/**
+ * SidePaneProps is a type that defines the properties for the SidePane component.
+ *
+ * It includes:
+ * - `title`: The heading title of the dialog.
+ * - `isOpen` and `onClose`: These props are conditionally required based on whether the component is controlled or uncontrolled.
+ *   - If `isOpen` is defined, `onClose` is required (controlled component).
+ *   - If `isOpen` is undefined, `onClose` is optional (uncontrolled component).
+ * - Additional props from `ComponentPropsWithoutRef<'div'>` are also included.
+ */
+export type SidePaneProps = {
+    /**
+     * The main content of the side pane.
+     */
+    children?: ReactNode;
+    /**
+     * The heading title of the dialog.
+     */
+    title?: string;
+    /**
+     * Custom render function for the heading area.
+     * Provides the original headingNode wrapped in <h2> tag for flexible layout composition.
+     * When provided, this takes precedence over the default title rendering.
+     *
+     * @param options - Contains the headingNode for layout composition
+     *
+     * @returns ReactNode - Custom layout containing the headingNode
+     *
+     * @example
+     * ```tsx
+     * <SidePane
+     *   title="Settings"
+     *   renderHeading={({ headingNode }) => (
+     *     <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+     *       <SettingsIcon />
+     *       {headingNode}
+     *     </div>
+     *   )}
+     * />
+     * ```
+     */
+    renderHeading?: (options: SidePaneRenderOptions) => ReactNode;
+    /**
+     * ReactNode which will be displayed on the right of the SidePane and on the left of Close Icon of the SidePane.
+     * Usually, we leave Buttons there
+     *
+     * @default undefined
+     */
+    actionSlot?: ReactNode;
+    /**
+     * The position of the side pane.
+     * This prop is optional. We only support two positions: 'left' and 'right'
+     *
+     * @default 'right'
+     */
+    position?: SidePaneSlotRecipeVariant['position'];
+    /**
+     * The properties for the close button.
+     * If this prop is not passed, the default values for each property will be applied.
+     *
+     * @property aria-label - The alternative text for the close button. default is '閉じる'.
+     *
+     * @property isCollapseIcon - Whether the close button displays a collapse icon instead of Close (X) icon.
+     *   If true, shows PaneExpansionToRight (>>) icon when position is 'right',
+     *   or PaneExpansionToLeft (<<) icon when position is 'left'.
+     *   default is false.
+     */
+    closeButtonProps?: {
+        isCollapseIcon?: boolean;
+    } & Pick<ComponentPropsWithoutRef<'button'>, 'aria-label'>;
+    /**
+     * The DOM node where the side pane should be rendered.
+     *
+     * If provided, the pane is rendered inside this node. Otherwise, a suitable DOM
+     * node is chosen automatically.
+     *
+     * @default undefined
+     */
+    targetDOMNode?: HTMLElement | null;
+    /**
+     * Enable modal mode of the SidePane. When set to true,
+     * the SidePane will render the backdrop and interaction
+     * with the underlying UI will be blocked.
+     *
+     * @default false
+     */
+    enableModal?: boolean;
+    /**
+     * Disables closing the side pane when clicking on the backdrop (modal mode only).
+     * When true, the side pane can only be closed via buttons or the close button.
+     *
+     * @default false
+     */
+    disableBackdropClose?: boolean;
+    /**
+     * Enable auto unmounting of the side pane content when it's not displayed.
+     * When true, the side pane content will return null instead of hiding via CSS.
+     *
+     * @default true
+     */
+    enableAutoUnmount?: boolean;
+    /**
+     * Additional props to apply to the inside container element of the SidePane.
+     * This element wraps the header and content sections.
+     *
+     * @default undefined
+     */
+    insideProps?: {
+        /**
+         * Additional class name to apply to the inside container element.
+         */
+        className?: string;
+    };
+    /**
+     * Whether the side pane is shown or not.
+     * This prop is required when using the side pane as a controlled component.
+     */
+    open?: boolean;
+    /**
+     * The handler to close the side pane.
+     * This prop is required when using the side pane as a controlled component.
+     */
+    onClose?: OnCloseFunction;
+} & Omit<ComponentPropsWithoutRef<'div'>, 'open' | 'onClose'>;

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

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

package/dist/esm/src/SidePane/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const ANIMATION_DURATION_IN = "0.35s";
+export declare const ANIMATION_DURATION_OUT_IN_MS = 250;
+export declare const ANIMATION_DURATION_OUT: string;

package/dist/esm/src/SidePane/constants.js

@@ -0,0 +1,3 @@
+export const ANIMATION_DURATION_IN = '0.35s';
+export const ANIMATION_DURATION_OUT_IN_MS = 250;
+export const ANIMATION_DURATION_OUT = `${(ANIMATION_DURATION_OUT_IN_MS / 1000).toString()}s`;

package/dist/esm/src/SidePane/hooks/useSidePaneOpenStateWithAnimation.d.ts

@@ -0,0 +1,8 @@
+export declare function useSidePaneOpenStateWithAnimation({ open, sidePaneElement, }: {
+    open: boolean | undefined;
+    sidePaneElement: HTMLDivElement | null;
+}): {
+    localOpen: boolean | undefined;
+    openSidePane: () => void;
+    closeSidePane: () => void;
+};

package/dist/esm/src/SidePane/hooks/useSidePaneOpenStateWithAnimation.js

@@ -0,0 +1,35 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { ANIMATION_DURATION_OUT_IN_MS } from '../constants';
+export function useSidePaneOpenStateWithAnimation({ open, sidePaneElement, }) {
+    const [localOpen, setLocalOpen] = useState(open);
+    const timerRef = useRef(null);
+    const openSidePane = useCallback(() => {
+        timerRef.current && clearTimeout(timerRef.current);
+        sidePaneElement?.classList.remove('out');
+        setLocalOpen(true);
+        sidePaneElement?.classList.add('in');
+    }, [sidePaneElement]);
+    const closeSidePane = useCallback(() => {
+        // Remove out class and add in class for animation
+        sidePaneElement?.classList.remove('in');
+        sidePaneElement?.classList.add('out');
+        // Clear timer if it exists
+        timerRef.current && clearTimeout(timerRef.current);
+        // MUST set timeout and wait until the animation is finished
+        timerRef.current = setTimeout(() => {
+            setLocalOpen(false);
+        }, ANIMATION_DURATION_OUT_IN_MS);
+    }, [sidePaneElement]);
+    // Cleanup timer on unmount
+    useEffect(() => () => {
+        if (timerRef.current) {
+            clearTimeout(timerRef.current);
+            timerRef.current = null;
+        }
+    }, []);
+    return {
+        localOpen,
+        openSidePane,
+        closeSidePane,
+    };
+}

package/dist/esm/src/SidePane/hooks/useSidePaneStateController.d.ts

@@ -0,0 +1,27 @@
+import { type ForwardedRef } from 'react';
+type UseSidePaneStateController = {
+    open?: boolean;
+    onClose?: () => void;
+    ref?: ForwardedRef<HTMLDivElement | null>;
+};
+/**
+ * Custom hook to control the open/close state of a SidePane.
+ *
+ * This hook provides functionality to open or close a SidePane based on the `open` flag.
+ *
+ * @param options - The options for controlling the SidePane state.
+ *
+ * @param options.open - Flag indicating if the SidePane should be open.
+ *
+ * @param options.onClose - Callback function to execute when closing the SidePane.
+ *
+ * @returns Object containing functions to handle closing the SidePane and ref Object to attach Dialog element.
+ */
+export declare function useSidePaneStateController({ open, onClose, ref }: UseSidePaneStateController): {
+    localOpen: boolean | undefined;
+    handleCloseSidePane: () => void;
+    handleStopCloseSidePane: (event: React.MouseEvent<HTMLDivElement>) => void;
+    sidePaneElement: HTMLDivElement | null;
+    setSidePaneElement: (element: HTMLDivElement | null) => void;
+};
+export {};