office-ui-fabric-react/lib-commonjs/components/GroupedList/GroupedList.types.d.ts

Reusable React components for building experiences for Microsoft 365.

import * as React from 'react';
import { GroupedListBase } from './GroupedList.base';
import { IList, IListProps } from '../../List';
import { IFocusZoneProps } from '../../FocusZone';
import { IRefObject, IRenderFunction, IStyleFunctionOrObject } from '../../Utilities';
import { IDragDropContext, IDragDropEvents, IDragDropHelper } from '../../utilities/dragdrop/index';
import { ISelection, SelectionMode } from '../../utilities/selection/index';
import { IViewport } from '../../utilities/decorators/withViewport';
import { ITheme, IStyle } from '../../Styling';
import { IGroupHeaderProps } from './GroupHeader.types';
import { IGroupShowAllProps } from './GroupShowAll.types';
import { IGroupFooterProps } from './GroupFooter.types';
/**
 * {@docCategory GroupedList}
 */
export declare enum CollapseAllVisibility {
    hidden = 0,
    visible = 1
}
/**
 * {@docCategory GroupedList}
 */
export interface IGroupedList extends IList {
    /**
     * Ensures that the list content is updated. Call this in cases where the list props don't change, but the list still
     * needs to be re-evaluated. For example, if a sizer bar is adjusted and causes the list width to change, you can
     * call this to force a re-evaluation. Be aware that this can be an expensive operation and should be done sparingly.
     */
    forceUpdate: () => void;
    /**
     * Toggles the collapsed state of all the groups in the list.
     */
    toggleCollapseAll: (allCollapsed: boolean) => void;
}
/**
 * {@docCategory GroupedList}
 */
export interface IGroupedListProps extends React.ClassAttributes<GroupedListBase> {
    /**
     * Theme that is passed in from Higher Order Component
     */
    theme?: ITheme;
    /**
     * Style function to be passed in to override the themed or default styles
     */
    styles?: IStyleFunctionOrObject<IGroupedListStyleProps, IGroupedListStyles>;
    /**
     * Optional callback to access the IGroupedList interface. Use this instead of ref for accessing
     * the public methods and properties of the component.
     */
    componentRef?: IRefObject<IGroupedList>;
    /** Optional class name to add to the root element. */
    className?: string;
    /** Boolean value to indicate if the component should render in compact mode. Set to false by default */
    compact?: boolean;
    /** Map of callback functions related to drag and drop functionality. */
    dragDropEvents?: IDragDropEvents;
    /** helper to manage drag/drop across item and groups */
    dragDropHelper?: IDragDropHelper;
    /** Event names and corresponding callbacks that will be registered to groups and rendered elements */
    eventsToRegister?: {
        eventName: string;
        callback: (context: IDragDropContext, event?: any) => void;
    }[];
    /** Optional override properties to render groups. */
    groupProps?: IGroupRenderProps;
    /** Optional grouping instructions. */
    groups?: IGroup[];
    /** List of items to render. */
    items: any[];
    /** Optional properties to pass through to the FocusZone. */
    focusZoneProps?: IFocusZoneProps;
    /** Optional properties to pass through to the list components being rendered. */
    listProps?: IListProps;
    /** Optional properties to pass through to the root list component being rendered. */
    rootListProps?: IListProps;
    /** Rendering callback to render the group items. */
    onRenderCell: (nestingDepth?: number, item?: any, index?: number) => React.ReactNode;
    /** Override the default role for GroupedList.  */
    role?: string;
    /** Optional selection model to track selection state.  */
    selection?: ISelection;
    /** Controls how/if the list manages selection. */
    selectionMode?: SelectionMode;
    /** Optional Viewport, provided by the parent component. */
    viewport?: IViewport;
    /** Optional callback when the group expand state changes between all collapsed and at least one group is expanded. */
    onGroupExpandStateChanged?: (isSomeGroupExpanded: boolean) => void;
    /**
     * boolean to control if pages containing unchanged items should be cached, this is a perf optimization
     * The same property in List.Props
     */
    usePageCache?: boolean;
    /**
     * Optional callback to determine whether the list should be rendered in full, or virtualized.
     * Virtualization will add and remove pages of items as the user scrolls them into the visible range.
     * This benefits larger list scenarios by reducing the DOM on the screen, but can negatively affect performance for
     * smaller lists.
     * The default implementation will virtualize when this callback is not provided.
     */
    onShouldVirtualize?: (props: IListProps) => boolean;
    /**
     * Optional function to override default group height calculation used by list virtualization.
     */
    getGroupHeight?: (group: IGroup, groupIndex: number) => number;
}
/**
 * {@docCategory GroupedList}
 */
export interface IGroup {
    /**
     * Unique identifier for the group.
     */
    key: string;
    /**
     * Display name for the group, rendered on the header.
     */
    name: string;
    /**
     * Start index for the group within the given items.
     */
    startIndex: number;
    /**
     * How many items should be rendered within the group.
     */
    count: number;
    /**
     * Nested groups, if any.
     */
    children?: IGroup[];
    /**
     * Number indicating the level of nested groups.
     */
    level?: number;
    /**
     * Deprecated at 1.0.0, selection state will be controled by the selection store only.
     * @deprecated At 1.0.0, selection state wil be controlled by the selection store only.
     */
    isSelected?: boolean;
    /**
     * If all the items in the group are collapsed.
     */
    isCollapsed?: boolean;
    /**
     * If the items within the group are summarized or showing all.
     */
    isShowingAll?: boolean;
    /**
     * If drag/drop is enabled for the group header.
     */
    isDropEnabled?: boolean;
    /**
     * Arbitrary data required to be preserved by the caller.
     */
    data?: any;
    /**
     * Optional accessibility label (aria-label) attribute that will be stamped on to the element.
     * If none is specified, the arai-label attribute will contain the group name
     */
    ariaLabel?: string;
    /**
     * Optional flag to indicate the group has more data to load than the current group count indicated.
     * This can be used to indicate that a plus should be rendered next to the group count in the header.
     */
    hasMoreData?: boolean;
}
/**
 * {@docCategory GroupedList}
 */
export interface IGroupRenderProps {
    /** Boolean indicating if all groups are in collapsed state. */
    isAllGroupsCollapsed?: boolean;
    /** Grouping item limit. */
    getGroupItemLimit?: (group: IGroup) => number;
    /** Callback for when all groups are expanded or collapsed. */
    onToggleCollapseAll?: (isAllCollapsed: boolean) => void;
    /** Information to pass in to the group header. */
    headerProps?: IGroupHeaderProps;
    /** Information to pass in to the group Show all footer. */
    showAllProps?: IGroupShowAllProps;
    /** Information to pass in to the group footer. */
    footerProps?: IGroupFooterProps;
    /**
     * Override which allows the caller to provide a custom header.
     */
    onRenderHeader?: IRenderFunction<IGroupHeaderProps>;
    /**
     * Override which allows the caller to provide a custom Show All link.
     */
    onRenderShowAll?: IRenderFunction<IGroupShowAllProps>;
    /**
     * Override which allows the caller to provide a custom footer.
     */
    onRenderFooter?: IRenderFunction<IGroupFooterProps>;
    /**
     * Flag to indicate whether to ignore the collapsing icon on header.
     * @defaultvalue CollapseAllVisibility.visible
     */
    collapseAllVisibility?: CollapseAllVisibility;
    /**
     * Boolean indicating if empty groups are shown
     * @defaultvalue false
     */
    showEmptyGroups?: boolean;
    /**
     * Override which allows the caller to provide a custom aria role
     */
    role?: string;
}
/**
 * {@docCategory GroupedList}
 */
export interface IGroupDividerProps {
    componentRef?: IRefObject<{}>;
    /** Boolean value to indicate if the component should render in compact mode. Set to false by default */
    compact?: boolean;
    /** Callback to determine if a group has missing items and needs to load them from the server. */
    isGroupLoading?: (group: IGroup) => boolean;
    /** Text shown on group headers to indicate the group is being loaded. */
    loadingText?: string;
    /** The group to be rendered by the header. */
    group?: IGroup;
    /** The index of the group. */
    groupIndex?: number;
    /** The indent level of the group. */
    groupLevel?: number;
    /** Defines the number of columns a group header needs to span in the case of a grid or treegrid */
    ariaColSpan?: number;
    /** Defines the number of items in the current set of listitems or treeitems */
    ariaSetSize?: number;
    /** Defines an element's number or position in the current set of listitems or treeitems */
    ariaPosInSet?: number;
    /** Defines the number of items in the current set of grid items */
    ariaRowCount?: number;
    /** Defines an element's number or position in the current set of grid items */
    ariaRowIndex?: number;
    /**
     * Width corresponding to a single level.
     * This is multiplied by the groupLevel to get the full spacer width for the group.
     */
    indentWidth?: number;
    /** If all items in the group are selected. */
    selected?: boolean;
    /**
     * Deprecated at v.65.1 and will be removed by v 1.0. Use `selected` instead.
     * @deprecated Use `selected` instead.
     */
    isSelected?: boolean;
    /** A reference to the viewport in which the header is rendered. */
    viewport?: IViewport;
    /** The selection mode of the list the group lives within. */
    selectionMode?: SelectionMode;
    /** Text to display for the group footer. */
    footerText?: string;
    /** Text to display for the group "Show All" link. */
    showAllLinkText?: string;
    /** Callback for when the group "Show All" link is clicked */
    onToggleSummarize?: (group: IGroup) => void;
    /** Callback for when the group header is clicked. */
    onGroupHeaderClick?: (group: IGroup) => void;
    /** Callback for when the "keyup" event is fired on the group header . */
    onGroupHeaderKeyUp?: (ev: React.KeyboardEvent<HTMLElement>, group: IGroup) => void;
    /** Callback for when the group is expanded or collapsed. */
    onToggleCollapse?: (group: IGroup) => void;
    /** Callback for when the group is selected. */
    onToggleSelectGroup?: (group: IGroup) => void;
    /** Determines if the group selection check box is shown for collapsed groups. */
    isCollapsedGroupSelectVisible?: boolean;
    /** Override which allows the caller to provider a custom renderer for the GroupHeader title. */
    onRenderTitle?: IRenderFunction<IGroupHeaderProps>;
    /** Override which allows the caller to provide a custom renderer for just the name. */
    onRenderName?: IRenderFunction<IGroupHeaderProps>;
    /** Props for expand/collapse button
     * @deprecated Use {@link IGroupHeaderProps.expandButtonProps} instead.
     */
    expandButtonProps?: React.HTMLAttributes<HTMLButtonElement>;
    /** Stores parent group's children. */
    groups?: IGroup[];
    /** Custom className */
    className?: string;
    /** Theme provided by the Higher Order Component */
    theme?: ITheme;
}
/**
 * {@docCategory GroupedList}
 */
export declare type IGroupedListStyleProps = Required<Pick<IGroupedListProps, 'theme'>> & Pick<IGroupedListProps, 'className'> & {
    /** whether or not the group is collapsed */
    isCollapsed?: boolean;
    /** Whether the group is in compact mode or not */
    compact?: boolean;
};
/**
 * {@docCategory GroupedList}
 */
export interface IGroupedListStyles {
    root: IStyle;
    group: IStyle;
    groupIsDropping: IStyle;
}