@lumx/react 4.12.1-next.2 → 4.13.0-next.0

package/index.d.ts

@@ -1,7 +1,7 @@
 import { HorizontalAlignment as HorizontalAlignment$1, Orientation as Orientation$1, Alignment as Alignment$1, Size as Size$1, AspectRatio as AspectRatio$1, Kind as Kind$1, Emphasis as Emphasis$1, Theme as Theme$1 } from '@lumx/core/js/constants';
 export * from '@lumx/core/js/constants';
 import * as _lumx_core_js_types from '@lumx/core/js/types';
-import { ValueOf as ValueOf$1, GenericProps as GenericProps$1, HasTheme as HasTheme$1, PropsToOverride, HasAriaDisabled as HasAriaDisabled$1, HasRequiredLinkHref as HasRequiredLinkHref$1, HasClassName as HasClassName$1, HasCloseMode as HasCloseMode$1, JSXElement as JSXElement$1, CommonRef as CommonRef$1, Falsy, HeadingElement as HeadingElement$1, HasAriaLabelOrLabelledBy as HasAriaLabelOrLabelledBy$1 } from '@lumx/core/js/types';
+import { ValueOf as ValueOf$1, GenericProps as GenericProps$1, HasTheme as HasTheme$1, PropsToOverride, HasAriaDisabled as HasAriaDisabled$1, HasRequiredLinkHref as HasRequiredLinkHref$1, HasClassName as HasClassName$1, HasCloseMode as HasCloseMode$1, JSXElement as JSXElement$1, CommonRef as CommonRef$1, Falsy, HeadingElement as HeadingElement$1, HasAriaLabelOrLabelledBy as HasAriaLabelOrLabelledBy$1, NamedProps } from '@lumx/core/js/types';
 export * from '@lumx/core/js/types';
 import * as React$1 from 'react';
 import React__default, { Ref, ReactElement, ReactNode, SyntheticEvent, MouseEventHandler, KeyboardEventHandler, RefObject, SetStateAction, Key, CSSProperties, ElementType as ElementType$1, HTMLInputTypeAttribute, ComponentProps, ImgHTMLAttributes } from 'react';
@@ -2098,6 +2098,8 @@ interface ComboboxButtonProps$1 extends HasClassName, ComboboxCallbacks {
     isOpen?: boolean;
     /** ref to the root button element. */
     ref?: CommonRef;
+    /** Custom render button */
+    renderButton?: (buttonProps: Record<string, any>) => JSXElement;
 }
 
 /**
@@ -4092,6 +4094,30 @@ interface SelectTextFieldTranslations {
     /** Secondary error message (e.g. "Please try again"). */
     errorTryReloadMessage?: string;
 }
+/**
+ * Shared translation labels for SelectButton wrappers (React and Vue).
+ */
+interface SelectButtonTranslations {
+    /** Screen reader loading announcement (e.g. "Loading…"). */
+    loadingMessage?: string;
+    /**
+     * Message to display when the list has no visible options.
+     * Can be a plain string or a function receiving the current input value (for dynamic messages).
+     * When omitted, the empty state is not shown.
+     */
+    emptyMessage?: string | ((inputValue: string) => string);
+    /**
+     * Message callback to display the number of available options.
+     * Called with the current visible option count and should return a human-readable string.
+     * Displayed when the dropdown is open, not empty, not loading, and not in error.
+     * When omitted, no option count message is shown.
+     */
+    nbOptionMessage?: (optionsLength: number) => string;
+    /** Error title displayed in the dropdown (e.g. "Failed to load"). */
+    errorMessage?: string;
+    /** Secondary error message (e.g. "Please try again"). */
+    errorTryReloadMessage?: string;
+}
 /**
  * Wrapper-level props shared between React and Vue SelectTextField implementations.
  * These are framework-specific concerns (not part of the core template) that both
@@ -4171,6 +4197,160 @@ interface BaseSelectTextFieldWrapperProps<O> extends Pick<BaseSelectProps<O>, 'o
     translations: SelectTextFieldTranslations;
 }
 
+/**
+ * Defines the props for the core SelectButton template.
+ */
+interface SelectButtonProps$1<O> extends BaseSelectProps<O> {
+    /**
+     * Selected value (single mode) or selected values (multi mode).
+     * The wrapper layer chooses the shape; the core just renders names.
+     */
+    value?: O | O[];
+    /**
+     * When `true`, sets `aria-multiselectable="true"` on the listbox so
+     * the dropdown stays open after each selection (combobox setup detects this attribute).
+     */
+    isMultiselectable?: boolean;
+    /** Button label (used for ARIA and when no selection). */
+    label: string;
+    /** Controls how the label/value is displayed in the button. */
+    labelDisplayMode?: ComboboxButtonLabelDisplayMode;
+    /**
+     * Props forwarded to Combobox.Button (button appearance, emphasis, size, etc.).
+     * Pass `renderButton` here to provide a custom button renderer — see
+     * `ComboboxButtonProps.renderButton`. Framework wrappers are responsible for
+     * defaulting any visual affordance (e.g. the dropdown chevron `rightIcon`).
+     */
+    buttonProps?: Record<string, any>;
+    /** Props forwarded to Combobox.Popover. */
+    popoverProps?: Record<string, any>;
+    /** Props forwarded to Combobox.List (e.g. ref). */
+    listProps?: Record<string, any>;
+    /** Callback on option selected (receives option id string). */
+    handleSelect?: (selectedOption: {
+        value: string;
+    }) => void;
+    /**
+     * Status of the dropdown list.
+     * - `'idle'` — Default state, no loading indicators.
+     * - `'loading'` — Full loading: shows skeleton placeholders, hides real options.
+     * - `'loadingMore'` — Paginated loading: appends a skeleton after existing options.
+     * - `'error'` — Error state: shows an error message in the dropdown.
+     * @default 'idle'
+     */
+    listStatus?: SelectTextFieldStatus;
+    /** Optional translations for screen-reader announcements (loading/empty/error/option count). */
+    translations?: SelectButtonTranslations;
+    /** Callback fired when the dropdown open state changes. */
+    onOpen?: (isOpen: boolean) => void;
+    /**
+     * Callback fired to load more items (infinite scroll).
+     * When provided together with an injected `InfiniteScroll` component, an invisible
+     * sentinel element is rendered after the options to trigger loading via IntersectionObserver.
+     */
+    onLoadMore?: () => void;
+    /** IntersectionObserver options forwarded to the InfiniteScroll sentinel. */
+    infiniteScrollOptions?: IntersectionObserverInit;
+}
+
+/** Default trigger: LumX `Button` with the dropdown chevron pre-applied. */
+declare const DefaultButton: Comp<ButtonProps, HTMLButtonElement>;
+/** Keys managed internally — never forwarded to the trigger element. */
+type OmittedKeys = 'value' | 'children' | 'role' | 'aria-controls' | 'aria-haspopup' | 'aria-expanded' | 'aria-activedescendant' | 'ref';
+/** Select-specific props common to both single and multi modes. */
+type SelectButtonSelectProps<O> = Omit<ReactToJSX<SelectButtonProps$1<O>>, 'renderOption' | 'buttonProps' | 'value' | 'isMultiselectable'> & {
+    /** Called to load more options (infinite scroll). */
+    onLoadMore?: () => void;
+    /** Called when the dropdown opens or closes. */
+    onOpen?: (isOpen: boolean) => void;
+    /**
+     * Custom option renderer. It should return a `<SelectButton.Option>`.
+     * Props `value`, `isSelected`, `description` and `key` are merged in automatically.
+     */
+    renderOption?: (option: O, index: number) => React__default.ReactNode;
+};
+/**
+ * Forwarded trigger props for a given element `E`, minus the keys that the
+ * component manages internally.
+ */
+type TriggerProps<E extends ElementType$1> = Omit<NamedProps<React__default.ComponentPropsWithoutRef<E>>, OmittedKeys>;
+/**
+ * Common base — Select-specific props plus the ARIA / label / popover layer.
+ * `as`, `ref`, `selectionType`, `value`, `onChange` are intentionally hoisted
+ * to the top-level `SelectButtonProps` shape (below) so that TS can infer
+ * `O`, `E`, and `S` directly from those JSX attributes.
+ */
+type CommonSelectButtonProps<O> = SelectButtonSelectProps<O> & GenericProps$1 & {
+    /** Button label, used for ARIA and as fallback when no option is selected. */
+    label: string;
+    /** Props forwarded to the popover. */
+    popoverProps?: ComboboxPopoverProps;
+    /** How the selected option is shown in the trigger. */
+    labelDisplayMode?: ComboboxButtonLabelDisplayMode;
+    /**
+     * Status of the dropdown list (loading, error, etc.).
+     * @default 'idle'
+     */
+    listStatus?: SelectTextFieldStatus;
+    /** Screen-reader translations (loading/empty/error/option count). */
+    translations?: SelectButtonTranslations;
+};
+/**
+ * Props for `SelectButton`.
+ *
+ * Polymorphic — pass `as` to render the trigger as a different component
+ * (e.g. `as={IconButton}`, `as={Chip}`, `as={Link}`). With no `as`, the trigger
+ * is the LumX `Button` with the dropdown chevron, so LumX `ButtonProps`
+ * (`emphasis`, `size`, `leftIcon`…) are accepted. With `as`, the trigger is
+ * fully replaced and only props valid for that component apply.
+ *
+ * Discriminated on `selectionType`:
+ * - default / `'single'` → `value?: O`, `onChange?: (newValue?: O) => void`.
+ * - `'multiple'`         → `value?: O[]`, `onChange?: (newValue?: O[]) => void`.
+ *
+ * `as` and `selectionType` are top-level on this type (rather than buried in
+ * an intersection or union member) so that TS can infer `E` from `as` and
+ * `S` from `selectionType` without explicit generic annotations at the call site.
+ *
+ * @typeParam O - Option object type, inferred from `options` / `getOptionId`.
+ * @typeParam E - Trigger element type, inferred from `as`. Defaults to the LumX `Button`.
+ * @typeParam S - Selection mode, inferred from `selectionType`. Defaults to `'single'`.
+ */
+type SelectButtonProps<O, E extends ElementType$1 = typeof DefaultButton, S extends 'single' | 'multiple' = 'single'> = CommonSelectButtonProps<O> & TriggerProps<E> & {
+    /** Customize the rendered trigger component. Inference site for `E`. */
+    as?: E;
+    /** Ref for the trigger element. Type follows `as`. */
+    ref?: ComponentRef<E>;
+    /**
+     * Selection mode discriminator. Inference site for `S`.
+     * Optional — defaults to `'single'`. Set to `'multiple'` to opt into
+     * multi-select; this also switches `value` / `onChange` to array form.
+     */
+    selectionType?: S;
+    /** Selected option(s). Shape depends on `selectionType`. */
+    value?: S extends 'multiple' ? O[] : O;
+    /** Called when the selection changes. Shape depends on `selectionType`. */
+    onChange?: S extends 'multiple' ? (newValue?: O[]) => void : (newValue?: O) => void;
+};
+/**
+ * Single-selection props (`selectionType` defaults to `'single'`).
+ * Backwards-compatible alias — existing consumers do not need to set `selectionType`.
+ */
+type SingleSelectButtonProps<O, E extends ElementType$1 = typeof DefaultButton> = SelectButtonProps<O, E, 'single'>;
+/** Multi-selection props (`selectionType: 'multiple'` is required to opt in). */
+type MultipleSelectButtonProps<O, E extends ElementType$1 = typeof DefaultButton> = SelectButtonProps<O, E, 'multiple'>;
+
+/**
+ * SelectButton compound component.
+ */
+declare const SelectButton: {
+    <O, E extends React$1.ElementType = Comp<ButtonProps, HTMLButtonElement>, S extends "single" | "multiple" = "single">(props: SelectButtonProps<O, E, S>): react_jsx_runtime.JSX.Element;
+    displayName: string;
+} & {
+    /** Selectable option within the dropdown list. */
+    Option: Comp<ComboboxOptionProps, HTMLLIElement>;
+};
+
 interface BaseSelectTextFieldProps<O = any> extends BaseSelectTextFieldWrapperProps<O>, HasClassName$1 {
     /**
      * Custom option render function. Must return a `<Combobox.Option>` element with custom
@@ -5314,5 +5494,5 @@ declare const ThemeProvider: React__default.FC<{
 /** Get the theme in the current context. */
 declare function useTheme(): ThemeContextValue;
 
-export { AlertDialog, Autocomplete, AutocompleteMultiple, Avatar, Badge, BadgeWrapper, Button, ButtonEmphasis, ButtonGroup, CLASSNAME, COMPONENT_NAME, Checkbox, Chip, ChipGroup, Combobox, CommentBlock, CommentBlockVariant, DEFAULT_PROPS, DatePicker, DatePickerControlled, DatePickerField, Dialog, Divider, DragHandle, Dropdown, ExpansionPanel, Flag, FlexBox, GenericBlock, GenericBlockGapSize, Grid, GridColumn, GridItem, Heading, HeadingLevelProvider, Icon, IconButton, ImageBlock, ImageBlockCaptionPosition, ImageLightbox, InlineList, InputHelper, InputLabel, Lightbox, Link, LinkPreview, List, ListDivider, ListItem, ListSection, ListSubheader, Message, Mosaic, Navigation, Notification, Placement, Popover, PopoverDialog, PostBlock, Progress, ProgressCircular, ProgressLinear, ProgressTracker, ProgressTrackerProvider, ProgressTrackerStep, ProgressTrackerStepPanel, ProgressVariant, RadioButton, RadioGroup, RawInputText, RawInputTextarea, Select, SelectMultiple, SelectMultipleField, SelectTextField, SelectVariant, SelectionChipGroup, SideNavigation, SideNavigationItem, SkeletonCircle, SkeletonRectangle, SkeletonRectangleVariant, SkeletonTypography, Slider, Slides, Slideshow, SlideshowControls, SlideshowItem, Switch, Tab, TabList, TabListLayout, TabPanel, TabProvider, Table, TableBody, TableCell, TableCellVariant, TableCellVariant as TableCellVariantType, TableHeader, TableRow, Text, TextField, ThOrder, ThOrder as ThOrderType, ThemeProvider, Thumbnail, ThumbnailAspectRatio, ThumbnailObjectFit, ThumbnailVariant, Toolbar, Tooltip, Uploader, UploaderVariant, UserBlock, clamp, useFocusPointStyle, useHeadingLevel, useTheme };
-export type { AlertDialogProps, AutocompleteMultipleProps, AutocompleteProps, AvatarProps, AvatarSize, BadgeProps, BadgeWrapperProps, BaseButtonProps, ButtonGroupProps, ButtonProps, ButtonSize, CheckboxProps, ChipGroupProps, ChipProps, ComboboxButtonProps, ComboboxInputProps, ComboboxListProps, ComboboxOptionActionProps, ComboboxOptionMoreInfoProps, ComboboxOptionProps, ComboboxOptionSkeletonProps, ComboboxPopoverComponentProps, ComboboxPopoverProps, ComboboxProviderProps, ComboboxSectionProps, ComboboxStateProps, CommentBlockProps, DatePickerControlledProps, DatePickerFieldProps, DatePickerProps, DialogProps, DialogSizes, DividerProps, DragHandleProps, DropdownProps, Elevation, ExpansionPanelProps, FlagProps, FlexBoxProps, FlexHorizontalAlignment, FlexVerticalAlignment, FocusPoint, GapSize, GenericBlockProps, GenericBlockSectionProps, GridColumnGapSize, GridColumnProps, GridItemProps, GridProps, HeadingLevelProviderProps, HeadingProps, IconButtonProps, IconProps, IconSizes, ImageBlockProps, ImageBlockSize, ImageLightboxProps, InlineListProps, InputHelperProps, InputLabelProps, LightboxProps, LinkPreviewProps, LinkProps, ListDividerProps, ListItemProps, ListItemSize, ListProps, ListSectionProps, ListSubheaderProps, MarginAutoAlignment, MessageProps, MosaicProps, MultipleSelectTextFieldProps, NavigationProps, NotificationProps, Offset, PopoverDialogProps, PopoverProps, PostBlockProps, ProgressCircularProps, ProgressCircularSize, ProgressLinearProps, ProgressProps, ProgressTrackerProps, ProgressTrackerProviderProps, ProgressTrackerStepPanelProps, ProgressTrackerStepProps, RadioButtonProps, RadioGroupProps, RawInputTextProps, RawInputTextareaProps, SelectMultipleProps, SelectProps, SelectTextFieldProps, SelectTextFieldStatus, SelectTextFieldTranslations, SelectionChipGroupProps, SideNavigationItemProps, SideNavigationProps, SingleSelectTextFieldProps, SkeletonCircleProps, SkeletonRectangleProps, SkeletonTypographyProps, SliderProps, SlidesProps, SlideshowControlsProps, SlideshowItemProps, SlideshowProps, SwitchProps, TabListProps, TabPanelProps, TabProps, TabProviderProps, TableBodyProps, TableCellProps, TableHeaderProps, TableProps, TableRowProps, TextFieldProps, TextProps, ThumbnailProps, ThumbnailSize, ToolbarProps, TooltipPlacement, TooltipProps, UploaderProps, UploaderSize, UserBlockProps, UserBlockSize };
+export { AlertDialog, Autocomplete, AutocompleteMultiple, Avatar, Badge, BadgeWrapper, Button, ButtonEmphasis, ButtonGroup, CLASSNAME, COMPONENT_NAME, Checkbox, Chip, ChipGroup, Combobox, CommentBlock, CommentBlockVariant, DEFAULT_PROPS, DatePicker, DatePickerControlled, DatePickerField, Dialog, Divider, DragHandle, Dropdown, ExpansionPanel, Flag, FlexBox, GenericBlock, GenericBlockGapSize, Grid, GridColumn, GridItem, Heading, HeadingLevelProvider, Icon, IconButton, ImageBlock, ImageBlockCaptionPosition, ImageLightbox, InlineList, InputHelper, InputLabel, Lightbox, Link, LinkPreview, List, ListDivider, ListItem, ListSection, ListSubheader, Message, Mosaic, Navigation, Notification, Placement, Popover, PopoverDialog, PostBlock, Progress, ProgressCircular, ProgressLinear, ProgressTracker, ProgressTrackerProvider, ProgressTrackerStep, ProgressTrackerStepPanel, ProgressVariant, RadioButton, RadioGroup, RawInputText, RawInputTextarea, Select, SelectButton, SelectMultiple, SelectMultipleField, SelectTextField, SelectVariant, SelectionChipGroup, SideNavigation, SideNavigationItem, SkeletonCircle, SkeletonRectangle, SkeletonRectangleVariant, SkeletonTypography, Slider, Slides, Slideshow, SlideshowControls, SlideshowItem, Switch, Tab, TabList, TabListLayout, TabPanel, TabProvider, Table, TableBody, TableCell, TableCellVariant, TableCellVariant as TableCellVariantType, TableHeader, TableRow, Text, TextField, ThOrder, ThOrder as ThOrderType, ThemeProvider, Thumbnail, ThumbnailAspectRatio, ThumbnailObjectFit, ThumbnailVariant, Toolbar, Tooltip, Uploader, UploaderVariant, UserBlock, clamp, useFocusPointStyle, useHeadingLevel, useTheme };
+export type { AlertDialogProps, AutocompleteMultipleProps, AutocompleteProps, AvatarProps, AvatarSize, BadgeProps, BadgeWrapperProps, BaseButtonProps, ButtonGroupProps, ButtonProps, ButtonSize, CheckboxProps, ChipGroupProps, ChipProps, ComboboxButtonProps, ComboboxInputProps, ComboboxListProps, ComboboxOptionActionProps, ComboboxOptionMoreInfoProps, ComboboxOptionProps, ComboboxOptionSkeletonProps, ComboboxPopoverComponentProps, ComboboxPopoverProps, ComboboxProviderProps, ComboboxSectionProps, ComboboxStateProps, CommentBlockProps, DatePickerControlledProps, DatePickerFieldProps, DatePickerProps, DialogProps, DialogSizes, DividerProps, DragHandleProps, DropdownProps, Elevation, ExpansionPanelProps, FlagProps, FlexBoxProps, FlexHorizontalAlignment, FlexVerticalAlignment, FocusPoint, GapSize, GenericBlockProps, GenericBlockSectionProps, GridColumnGapSize, GridColumnProps, GridItemProps, GridProps, HeadingLevelProviderProps, HeadingProps, IconButtonProps, IconProps, IconSizes, ImageBlockProps, ImageBlockSize, ImageLightboxProps, InlineListProps, InputHelperProps, InputLabelProps, LightboxProps, LinkPreviewProps, LinkProps, ListDividerProps, ListItemProps, ListItemSize, ListProps, ListSectionProps, ListSubheaderProps, MarginAutoAlignment, MessageProps, MosaicProps, MultipleSelectButtonProps, MultipleSelectTextFieldProps, NavigationProps, NotificationProps, Offset, PopoverDialogProps, PopoverProps, PostBlockProps, ProgressCircularProps, ProgressCircularSize, ProgressLinearProps, ProgressProps, ProgressTrackerProps, ProgressTrackerProviderProps, ProgressTrackerStepPanelProps, ProgressTrackerStepProps, RadioButtonProps, RadioGroupProps, RawInputTextProps, RawInputTextareaProps, SelectButtonProps, SelectButtonTranslations, SelectMultipleProps, SelectProps, SelectTextFieldProps, SelectTextFieldStatus, SelectTextFieldTranslations, SelectionChipGroupProps, SideNavigationItemProps, SideNavigationProps, SingleSelectButtonProps, SingleSelectTextFieldProps, SkeletonCircleProps, SkeletonRectangleProps, SkeletonTypographyProps, SliderProps, SlidesProps, SlideshowControlsProps, SlideshowItemProps, SlideshowProps, SwitchProps, TabListProps, TabPanelProps, TabProps, TabProviderProps, TableBodyProps, TableCellProps, TableHeaderProps, TableProps, TableRowProps, TextFieldProps, TextProps, ThumbnailProps, ThumbnailSize, ToolbarProps, TooltipPlacement, TooltipProps, UploaderProps, UploaderSize, UserBlockProps, UserBlockSize };