react-collapsed/dist/index.d.mts

A React custom-hook for creating flexible and accessible expand/collapse components.

/**
  * react-collapsed v4.2.0
  *
  * Copyright (c) 2019-2024, Rogin Farrer
  *
  * This source code is licensed under the MIT license found in the
  * LICENSE.md file in the root directory of this source tree.
  *
  * @license MIT
  */

import * as react from 'react';
import { MutableRefObject, CSSProperties } from 'react';

/**
 * React.Ref uses the readonly type `React.RefObject` instead of
 * `React.MutableRefObject`, We pretty much always assume ref objects are
 * mutable (at least when we create them), so this type is a workaround so some
 * of the weird mechanics of using refs with TS.
 */
type AssignableRef<ValueType> = {
    bivarianceHack(instance: ValueType | null): void;
}['bivarianceHack'] | MutableRefObject<ValueType | null>;

interface UseCollapseInput {
    /**
     * If true, the collapsible element is expanded.
     */
    isExpanded?: boolean;
    /**
     * If true, the collapsible element is expanded when it initially mounts.
     * @default false
     */
    defaultExpanded?: boolean;
    /**
     * Sets the height (Number) to which the elements collapses.
     * @default 0
     */
    collapsedHeight?: number;
    /**
     * Sets the transition-timing-function of the animation.
     * @default 'cubic-bezier(0.4, 0, 0.2, 1)'
     */
    easing?: string;
    /**
     * Sets the duration of the animation. If undefined, a 'natural' duration is
     * calculated based on the distance of the animation.
     */
    duration?: number;
    /**
     * If true, the animation is disabled. Overrides the hooks own logic for
     * disabling the animation according to reduced motion preferences.
     */
    hasDisabledAnimation?: boolean;
    /**
     * Handler called at each stage of the animation.
     */
    onTransitionStateChange?: (state: 'expandStart' | 'expandEnd' | 'expanding' | 'collapseStart' | 'collapseEnd' | 'collapsing') => void;
    /**
     * Unique identifier used to for associating elements appropriately for accessibility.
     */
    id?: string | number;
}
declare function useCollapse({ duration, easing, onTransitionStateChange: propOnTransitionStateChange, isExpanded: configIsExpanded, defaultExpanded, hasDisabledAnimation, id, ...initialConfig }?: UseCollapseInput): {
    isExpanded: boolean;
    setExpanded: (update: boolean | ((value: boolean) => boolean)) => void;
    getToggleProps<Args extends {
        [k: string]: unknown;
        onClick?: react.MouseEventHandler<Element> | undefined;
        disabled?: boolean | undefined;
    }, RefKey extends string | undefined = "ref">(args?: Args & {
        /**
         * Sets the key of the prop that the component uses for ref assignment
         * @default 'ref'
         */
        refKey?: RefKey;
    }): { [K in RefKey extends string ? RefKey : "ref"]: AssignableRef<any>; } & {
        onClick: React.MouseEventHandler;
        id: string;
        'aria-controls': string;
        'aria-expanded'?: boolean | undefined;
        type?: "button" | undefined;
        disabled?: boolean | undefined;
        'aria-disabled'?: boolean | undefined;
        role?: "button" | undefined;
        tabIndex?: number | undefined;
    };
    getCollapseProps<Args_1 extends {
        [k: string]: unknown;
        style?: CSSProperties | undefined;
    }, RefKey_1 extends string | undefined = "ref">(args?: (Args_1 & {
        /**
         * Sets the key of the prop that the component uses for ref assignment
         * @default 'ref'
         */
        refKey?: RefKey_1 | undefined;
    }) | undefined): { [K_1 in RefKey_1 extends string ? RefKey_1 : "ref"]: AssignableRef<any>; } & {
        id: string;
        'aria-hidden': boolean;
        role: string;
        style: CSSProperties;
    };
};

export { type UseCollapseInput, useCollapse };