@hypothesis/frontend-shared/lib/components/input/Select.d.ts

Shared components, styles and utilities for Hypothesis projects

import type { ComponentChildren, JSX, Ref } from 'preact';
import type { CompositeProps } from '../../types';
import type { ListboxOverflow } from './SelectContext';
export type SelectOptionStatus = {
    selected: boolean;
    disabled: boolean;
};
export type SelectOptionProps<T> = {
    /**
     * An undefined value in a multiple select will cause the selection to reset
     * to an empty array.
     */
    value: T | undefined;
    disabled?: boolean;
    children: ComponentChildren | ((status: SelectOptionStatus) => ComponentChildren);
    classes?: string | string[];
    /** Ref associated with the option's container element */
    elementRef?: Ref<HTMLElement | undefined>;
    /** Value to be passed to the option's `title` attribute */
    title?: string;
};
declare function SelectOption<T>({ value, children, disabled, classes, elementRef, title, }: SelectOptionProps<T>): JSX.Element;
declare namespace SelectOption {
    var displayName: string;
}
type SingleValueProps<T> = {
    value: T;
    onChange: (newValue: T) => void;
};
type MultiValueProps<T> = {
    value: T[];
    onChange: (newValue: T[]) => void;
};
type BaseSelectProps = CompositeProps & {
    buttonContent?: ComponentChildren;
    disabled?: boolean;
    /**
     * `id` attribute for the toggle button. This is useful to associate a label
     * with the control.
     */
    buttonId?: string;
    /** Additional classes to pass to container */
    containerClasses?: string | string[];
    /** Additional classes to pass to toggle button */
    buttonClasses?: string | string[];
    /** Additional classes to pass to the popover */
    popoverClasses?: string | string[];
    /**
     * How to align the listbox relative to the toggle button.
     *
     * Useful when rendering a Select with a big listbox, close to the right side
     * of the viewport. In that case it looks nicer if the listbox aligns with the
     * right side of the toggle button and extends to the left.
     * Defaults to 'left'.
     */
    alignListbox?: 'left' | 'right';
    'aria-label'?: string;
    'aria-labelledby'?: string;
    /**
     * Used to determine if the listbox should use the popover API.
     * Defaults to true, as long as the browser supports it.
     */
    listboxAsPopover?: boolean;
    /** A callback passed to the popover onScroll */
    onPopoverScroll?: JSX.HTMLAttributes<HTMLElement>['onScroll'];
    /**
     * Indicates how overflowing content should be handled in the listbox.
     *
     * - `truncate`: Truncate the options via `text-overflow: ellipsis`, so that
     *               they all fit in one line. This is the default value.
     * - `wrap`: Let options content wrap onto multiple lines via
     *           `white-space: normal`
     *
     * Complex content may still need to provide its own styling to handle content
     * overflow.
     */
    listboxOverflow?: ListboxOverflow;
};
export type SelectProps<T> = BaseSelectProps & SingleValueProps<T>;
export type MultiSelectProps<T> = BaseSelectProps & MultiValueProps<T>;
export declare const Select: (<T>(props: SelectProps<T>) => JSX.Element) & {
    Option: typeof SelectOption;
    displayName: string;
};
export declare const MultiSelect: (<T>(props: MultiSelectProps<T>) => JSX.Element) & {
    Option: typeof SelectOption;
    displayName: string;
};
export {};