@payfit/unity-components
Version:
119 lines (118 loc) • 4.87 kB
TypeScript
import { ListBoxSectionProps } from 'react-aria-components/ListBox';
export declare const selectListOptGroup: import('tailwind-variants').TVReturnType<{
[key: string]: {
[key: string]: import('tailwind-merge').ClassNameValue | {
base?: import('tailwind-merge').ClassNameValue;
label?: import('tailwind-merge').ClassNameValue;
separator?: import('tailwind-merge').ClassNameValue;
};
};
} | {
[x: string]: {
[x: string]: import('tailwind-merge').ClassNameValue | {
base?: import('tailwind-merge').ClassNameValue;
label?: import('tailwind-merge').ClassNameValue;
separator?: import('tailwind-merge').ClassNameValue;
};
};
} | {}, {
base: string;
label: string;
separator: string;
}, undefined, {
[key: string]: {
[key: string]: import('tailwind-merge').ClassNameValue | {
base?: import('tailwind-merge').ClassNameValue;
label?: import('tailwind-merge').ClassNameValue;
separator?: import('tailwind-merge').ClassNameValue;
};
};
} | {}, {
base: string;
label: string;
separator: string;
}, import('tailwind-variants').TVReturnType<unknown, {
base: string;
label: string;
separator: string;
}, undefined, unknown, unknown, undefined>>;
/**
* Props for the SelectListOptGroup component.
* @template TType - The type of items when using the dynamic API
*/
export interface SelectListOptGroupProps<TType extends object> extends ListBoxSectionProps<TType> {
/**
* The heading text for this group of options. Displayed above the group's options to provide visual and semantic organization.
*/
label: string;
/**
* Adds a visual separator line below this group to create clear visual boundaries between groups. Set to `true` to enhance visual separation.
* @default false
*/
withSeparator?: boolean;
}
/**
* Organizes related options into labeled sections within a `SelectList` component.
* Use this component to group related options together under a common label, improving scannability and organization for users. The component supports both static (directly nested children) and dynamic (items array with render function) APIs, and can optionally display a separator line to create clear visual boundaries between groups.
* @param {SelectListOptGroupProps} props - Regular props from React Aria's ListBoxSection, plus label and separator configuration
* @example
* ```tsx
* import { SelectList, SelectListOptGroup, SelectListOption } from '@payfit/unity-components'
*
* function Example() {
* const sections = [
* {
* id: 'fruits',
* label: 'Fruits',
* children: [
* { id: 'apple', label: 'Apple' },
* { id: 'banana', label: 'Banana' }
* ]
* },
* {
* id: 'vegetables',
* label: 'Vegetables',
* children: [
* { id: 'carrot', label: 'Carrot' },
* { id: 'lettuce', label: 'Lettuce' }
* ]
* }
* ]
*
* return (
* <SelectList items={sections} selectionMode="multiple" value={new Set()} onChange={() => {}}>
* {section => (
* <SelectListOptGroup
* id={section.id}
* label={section.label}
* items={section.children}
* withSeparator
* >
* {item => (
* <SelectListOption id={item.id}>
* {item.label}
* </SelectListOption>
* )}
* </SelectListOptGroup>
* )}
* </SelectList>
* )
* }
* ```
* @remarks
* - Use the `label` prop to provide a descriptive heading that clearly identifies the group's category
* - Set `withSeparator` to `true` to add a visual separator line below the group for enhanced visual organization
* - Supports both static API (directly nest `SelectListOption` components) and dynamic API (provide `items` array with render function)
* - This component must be used within a `SelectList` parent component to function properly
* - Groups are accessible with proper ARIA semantics for screen readers
* @see {@link SelectListOptGroupProps} for all available props
* @see {@link SelectListOption} for the child option component
* @see {@link SelectList} for the parent component's API
* @see Source code in {@link https://github.com/PayFit/hr-apps/tree/master/libs/shared/unity/components/src/components/select-list/parts GitHub}
* @see Developer docs in {@link https://unity-components.payfit.io/?path=/docs/data-selectlist-selectlistoptgroup unity-components.payfit.io}
*/
declare function SelectListOptGroup<T extends object>(props: SelectListOptGroupProps<T>): import("react/jsx-runtime").JSX.Element;
declare namespace SelectListOptGroup {
var displayName: string;
}
export { SelectListOptGroup };