@patreon/studio/module/components/Dropdown/types.d.ts

Patreon Studio Design System

import type React from 'react';
import type { InlineHelpTextProps } from '~/components/InlineHelpText';
export type MaxHeight = 'none' | 'fill-available' | 'fit-content' | 'max-content' | 'min-content';
export type Width = 'auto' | 'fit-content' | '100%' | 'inherit' | 'max-content' | 'min-content';
export interface ItemProps {
    /**
     * Whether item is disabled. Will prevent clicking.
     */
    disabled?: boolean;
    /**
     * Whether this item is currently highlighted (hover over or keyboard nav)
     */
    isHighlighted?: boolean;
    /**
     * Whether this item is currently selected/active
     */
    isSelected?: boolean;
    /**
     * The text label to be shown for the item
     */
    label: string;
    /**
     * If a url is given, each item will be rendered as an anchor with a href to that url
     */
    url?: string;
}
export type ItemRenderer<T extends ItemProps = ItemProps> = (item: T) => React.ReactNode;
export type SelectItemHandler<T extends ItemProps = ItemProps> = (selectedItem: T, index: number, e: React.MouseEvent<HTMLElement> | KeyboardEvent) => void;
interface DropdownHandleComponent<P> {
    component: React.ComponentType<P>;
    props: P;
}
export type ContainerElement = HTMLDivElement | null;
export type ActivatorElement = HTMLDivElement | HTMLButtonElement | null;
export interface DropdownPopperProps {
    children: (props: InjectedDropdownPopperProps) => JSX.Element;
    rightAlign?: boolean;
    autoUpdate?: boolean;
    fluidDropdownList?: DropdownProps['fluidDropdownList'];
}
interface InjectedDropdownPopperProps {
    hostRef: React.Ref<ActivatorElement>;
    floatingRef: React.Ref<ContainerElement>;
    floatingStyles: React.CSSProperties;
}
export interface DropdownProps<HandleProps = Record<string, never>> extends React.AriaAttributes {
    /**
     * Label describing this dropdown for screen readers to read aloud
     */
    ariaLabel: string;
    children: React.ReactNode;
    /**
     * Whether the dropdown should close when the user clicks outside
     * or presses the Escape key
     */
    closeOnOutsideClick?: boolean;
    /**
     * Whether the dropdown functionality is disabled.
     * If it is disabled, it cannot be opened.
     */
    disabled?: boolean;
    /**
     * When defined renders `Dropdown` with error styles and error text below.
     */
    error?: InlineHelpTextProps['error'];
    /**
     * JSX or string of the selected item to render within the dropdown handle
     * Note: No need to add the Down/Up caret; they're handled by the Dropdown component
     */
    displayValue?: React.ReactNode;
    /**
     * React component to render instead of the default dropdown handle.
     * `displayValue` and `placeholder` values will be rendered inside of this
     * e.g. a fully bordered Block or a Button
     */
    dropdownHandle?: DropdownHandleComponent<HandleProps>;
    /**
     * Enables dropdown to stretch to full width of parent container
     */
    fluidWidth?: boolean;
    /**
     * Enables dropdown list to stretch to full width of the Dropdown handle.
     */
    fluidDropdownList?: boolean;
    /**
     * If you're providing your own button via dropdownHandle, use this to avoid nesting <button> elements.
     */
    hasCustomButton?: boolean;
    /**
     * Header text to display above children in the open dropdown container
     */
    header?: string;
    /**
     * Enable to disable open/close caret
     */
    hideCaret?: boolean;
    /**
     * HTML id property.
     */
    id?: string;
    /**
     * Whether the dropdown container is visible or not.
     */
    isOpen?: boolean;
    isDivDropdown?: boolean;
    /**
     * Max height (in units) of dropdown container, past
     * which it begins to scroll its contents.
     */
    maxHeight?: number | MaxHeight;
    /**
     * Min width (in units) of dropdown handle + container.
     * Defaults to width of `displayValue` or width of parent
     */
    minWidth?: number;
    /**
     * Eliminates input styles on Dropdown handle
     */
    noHandleStyle?: boolean;
    /**
     * Callback for when the dropdown is opened
     */
    onOpen?: (e: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement> | MouseEvent | KeyboardEvent) => void;
    /**
     * Callback for when the dropdown is closed
     */
    onClose?: (e: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement> | MouseEvent | KeyboardEvent) => void;
    /**
     * Whether to open the dropdown on handle hover
     * rather than handle click
     */
    openOnHover?: boolean;
    /**
     * JSX or string of the placeholder the dropdown handle displays before a selection is made.
     * e.g. This is what's shown when the dropdown is collapsed,
     * and is generally a placeholder like 'Select a reward...'
     */
    placeholder?: React.ReactNode;
    /**
     * Align the dropdown container to the right instead of the left
     * of the dropdown handle
     */
    rightAlign?: boolean;
    /**
     * Auto updates the position of the dropdown when the handle relocates.
     * Only use this option when you need it since there is a perf cost.
     */
    autoUpdatePosition?: boolean;
    /**
     * A CSS Width value (e.g. min-content or initial) or a number of units
     * for how wide the dropdown should be
     */
    width?: Width | number | string;
    /**
     * Where in the document to place the popover DOM.
     * @default "portal"
     */
    renderMode?: 'adjacent' | 'portal';
    /**
     * This is a temp fix see: https://github.com/Patreon/studio/issues/1265
     * Disables overflow on the dropdown container.
     */
    hideOverflow?: boolean;
}
export {};