@momentum-ui/react-collaboration/dist/cjs/hooks/useItemSelected.d.ts

Cisco Momentum UI Framework for React Collaboration Applications

export type SelectionMode = 'none' | 'single' | 'multiple';
export interface UseItemSelectedProps<TItemId extends string | number> {
    /**
     * Selection mode
     */
    selectionMode: SelectionMode;
    /**
     * List of items that should be selected by default
     */
    selectedByDefault?: Array<TItemId>;
    /**
     * Callback function when selection changes
     */
    onSelectionChange?: (selectedItems: Array<TItemId>) => void;
    /**
     * When it is `true`, at lest one item should be selected in other than `none` selection mode.
     * @default false
     */
    isRequired?: boolean;
    /**
     * List of selected items
     *
     * If it is provided, the selection will be controlled.
     * @default undefined
     *
     * @see {@link https://react.dev/reference/react-dom/components/input#controlling-an-input-with-a-state-variable Controlling an input with a state variable}
     */
    selectedItems?: Array<TItemId>;
}
export interface ItemSelection<TItemId extends string | number> {
    /**
     * Selection mode.
     */
    selectionMode: SelectionMode;
    /**
     * List of selected items.
     */
    selectedItems: Array<TItemId>;
    /**
     * Check if item is selected.
     * @param itemId Item identifier
     */
    isSelected: (itemId: TItemId) => boolean;
    /**
     * Toggle item selection
     *
     * Add `itemId` when `value` is `true`  and remove it when `value` is `false`,
     * if `value` is not provided, it will toggle the selection.
     *
     * When `isRequired` is `true`, it will not remove the last selected item.
     *
     * It should be used when you want to update a single item.
     *
     * @param itemId Item identifier
     * @param value
     */
    toggle: (itemId: TItemId, value?: boolean) => void;
    /**
     * Update selection with new list of selected items.
     * `isRequired` will be ignored.
     *
     * It is useful when you want to batch change the selection,
     * for example, when you want to select all items, or invert selection.
     *
     * It preferred to use this method over `toggle` when you want to update multiple items the same time.
     *
     * @param allSelectedItems List of selected items
     */
    update: (allSelectedItems: Array<TItemId>) => void;
    /**
     * Clear all selected items
     * `isRequired` will be ignored.
     */
    clear: () => void;
}
/**
 * Hook to manage selected items
 *
 * This hook support controlled and uncontrolled selection, and it works the same way as input components in React.
 *
 * Uncontrolled is the default state, when `selectedItems` is `undefined`.
 * In this case, the hook will manage the selection state internally.
 *
 * @example
 * ```tsx
 * const {selectedItems, isSelected, toggle, update, clear } = useItemSelected({
 *  selectionMode: 'multiple'
 * })
 * ```
 *
 * Controlled selection is when `selectedItems` is provided, and it isn't `undefined`.
 * This way the consumer of the hook can change the selection from outside.
 * Order to update this outside state, the `onSelectionChange` callback should be passed as well
 *
 * @example
 * ```tsx
 * const [selection, setSelection] = useState<Array<string>>([]);
 *
 * const {isSelected, toggle, update, clear } = useItemSelected({
 *  selectionMode: 'multiple',
 *  selectedItems: selection,
 *  onSelectionChange: setSelection,
 *  isRequired: true,
 * })
 * ```
 *
 * @param param Hook options
 */
export declare const useItemSelected: <TItemId extends string | number>({ selectionMode, selectedByDefault, onSelectionChange, selectedItems: selectedItemsFromProps, isRequired, }: UseItemSelectedProps<TItemId>) => ItemSelection<TItemId>;