@lumx/react 4.17.1-alpha.2 → 4.17.1-alpha.3

package/_internal/components/select/Select.js

@@ -0,0 +1,130 @@
+import { forwardRef } from "../../utils/react/forwardRef.js";
+import { mergeRefs } from "../../utils/react/mergeRefs.js";
+import { useTheme } from "../../utils/theme/ThemeContext.js";
+import { IconButton } from "../button/IconButton.js";
+import { Chip } from "../chip/Chip.js";
+import { Icon } from "../icon/Icon.js";
+import { InputLabel } from "../input-label/InputLabel.js";
+import { WithSelectContext } from "./WithSelectContext.js";
+import { SelectVariant } from "./constants.js";
+import { Emphasis, Size, Theme } from "@lumx/core/js/constants";
+import { mdiAlertCircle } from "@lumx/icons/esm/alert-circle.js";
+import { mdiCheckCircle } from "@lumx/icons/esm/check-circle.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { classNames } from "@lumx/core/js/utils";
+import isEmpty from "lodash/isEmpty.js";
+import { mdiCloseCircle } from "@lumx/icons/esm/close-circle.js";
+import { mdiMenuDown } from "@lumx/icons/esm/menu-down.js";
+//#region src/components/select/Select.tsx
+/** The display name of the component. */
+var COMPONENT_NAME = "Select";
+/** The default class name and classes prefix for this component. */
+var CLASSNAME = "lumx-select";
+var { block, element } = classNames.bem(CLASSNAME);
+/** The default value of props. */
+var DEFAULT_PROPS = {
+	selectedValueRender: (choice) => choice,
+	variant: SelectVariant.input
+};
+var stopPropagation = (evt) => evt.stopPropagation();
+/**
+* Select component.
+*/
+var SelectField = (props) => {
+	const defaultTheme = useTheme();
+	const { anchorRef, clearButtonProps, handleKeyboardNav, hasError, hasInputClear, icon, id, isDisabled, isEmpty, isRequired, isValid, label, onClear, onInputClick, placeholder, selectedValueRender, theme = defaultTheme, value, variant, selectElementRef, ...forwardedProps } = props;
+	return /* @__PURE__ */ jsxs(Fragment, { children: [variant === SelectVariant.input && /* @__PURE__ */ jsxs(Fragment, { children: [label && /* @__PURE__ */ jsx("div", {
+		className: element("header"),
+		children: /* @__PURE__ */ jsx(InputLabel, {
+			htmlFor: id,
+			className: element("label"),
+			isRequired,
+			theme,
+			children: label
+		})
+	}), /* @__PURE__ */ jsxs("div", {
+		ref: mergeRefs(anchorRef, selectElementRef),
+		id,
+		className: element("wrapper"),
+		onClick: onInputClick,
+		onKeyDown: handleKeyboardNav,
+		tabIndex: isDisabled ? void 0 : 0,
+		"aria-disabled": isDisabled || void 0,
+		...forwardedProps,
+		children: [
+			icon && /* @__PURE__ */ jsx(Icon, {
+				className: element("input-icon"),
+				color: theme === Theme.dark ? "light" : void 0,
+				icon,
+				size: Size.xs
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: element("input-native", { placeholder: isEmpty && placeholder }),
+				children: [!isEmpty && /* @__PURE__ */ jsx("span", { children: selectedValueRender?.(value) }), isEmpty && placeholder && /* @__PURE__ */ jsx("span", { children: placeholder })]
+			}),
+			(isValid || hasError) && /* @__PURE__ */ jsx("div", {
+				className: element("input-validity"),
+				children: /* @__PURE__ */ jsx(Icon, {
+					icon: isValid ? mdiCheckCircle : mdiAlertCircle,
+					size: Size.xxs
+				})
+			}),
+			hasInputClear && clearButtonProps && /* @__PURE__ */ jsx(IconButton, {
+				...clearButtonProps,
+				className: element("input-clear"),
+				icon: mdiCloseCircle,
+				emphasis: Emphasis.low,
+				size: Size.s,
+				theme,
+				onClick: onClear,
+				onKeyDown: stopPropagation
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: element("input-indicator"),
+				children: /* @__PURE__ */ jsx(Icon, {
+					icon: mdiMenuDown,
+					size: Size.s
+				})
+			})
+		]
+	})] }), variant === SelectVariant.chip && /* @__PURE__ */ jsxs(Chip, {
+		id,
+		isSelected: !isEmpty,
+		isDisabled,
+		after: /* @__PURE__ */ jsx(Icon, { icon: isEmpty ? mdiMenuDown : mdiCloseCircle }),
+		onAfterClick: isEmpty ? onInputClick : onClear,
+		onClick: onInputClick,
+		ref: mergeRefs(anchorRef, selectElementRef),
+		theme,
+		...forwardedProps,
+		children: [isEmpty && /* @__PURE__ */ jsx("span", { children: label }), !isEmpty && /* @__PURE__ */ jsx("span", { children: selectedValueRender?.(value) })]
+	})] });
+};
+/**
+* Select component.
+*
+* @deprecated use `SelectTextField` instead
+* @param  props Component props.
+* @param  ref   Component ref.
+* @return React element.
+*/
+var Select = forwardRef((props, ref) => {
+	const isEmpty$1 = isEmpty(props.value);
+	const hasInputClear = props.onClear && props.clearButtonProps && !isEmpty$1;
+	return WithSelectContext(SelectField, {
+		...DEFAULT_PROPS,
+		...props,
+		className: classNames.join(props.className, block({
+			"has-input-clear": hasInputClear,
+			"has-unique": !props.isEmpty
+		})),
+		hasInputClear,
+		isEmpty: isEmpty$1
+	}, ref);
+});
+Select.displayName = COMPONENT_NAME;
+Select.className = CLASSNAME;
+Select.defaultProps = DEFAULT_PROPS;
+Select.className = CLASSNAME;
+//#endregion
+export { Select };

package/_internal/components/select/SelectMultiple.d.ts

@@ -0,0 +1,24 @@
+import { Comp } from "../../utils/type/Comp.js";
+import { CoreSelectProps } from "./constants.js";
+import { ReactNode, SyntheticEvent } from "react";
+
+//#region src/components/select/SelectMultiple.d.ts
+/** Defines the props of the component. */
+interface SelectMultipleProps extends CoreSelectProps {
+  /** Selected values. */
+  value: string[];
+  /** Selected value render function. Default: Renders the value inside of a Chip. */
+  selectedChipRender?(choice: string, index: number, onClear?: (event?: SyntheticEvent, choice?: string) => void, isDisabled?: boolean, theme?: any): ReactNode | string;
+}
+declare const SelectMultipleField: React.FC<SelectMultipleProps>;
+/**
+ * SelectMultiple component.
+ *
+ * @deprecated use `SelectTextField` instead
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+declare const SelectMultiple: Comp<SelectMultipleProps, HTMLDivElement>;
+//#endregion
+export { SelectMultiple, SelectMultipleField, SelectMultipleProps };

package/_internal/components/select/SelectMultiple.js

@@ -0,0 +1,128 @@
+import { forwardRef } from "../../utils/react/forwardRef.js";
+import { mergeRefs } from "../../utils/react/mergeRefs.js";
+import { useTheme } from "../../utils/theme/ThemeContext.js";
+import { Chip } from "../chip/Chip.js";
+import { Icon } from "../icon/Icon.js";
+import { InputLabel } from "../input-label/InputLabel.js";
+import { WithSelectContext } from "./WithSelectContext.js";
+import { SelectVariant } from "./constants.js";
+import { Size, Theme } from "@lumx/core/js/constants";
+import { mdiAlertCircle } from "@lumx/icons/esm/alert-circle.js";
+import { mdiCheckCircle } from "@lumx/icons/esm/check-circle.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { classNames } from "@lumx/core/js/utils";
+import { mdiClose } from "@lumx/icons/esm/close.js";
+import { mdiCloseCircle } from "@lumx/icons/esm/close-circle.js";
+import { mdiMenuDown } from "@lumx/icons/esm/menu-down.js";
+//#region src/components/select/SelectMultiple.tsx
+/** The display name of the component. */
+var COMPONENT_NAME = "Select";
+/** The default class name and classes prefix for this component. */
+var CLASSNAME = "lumx-select";
+var { block, element } = classNames.bem(CLASSNAME);
+/** The default value of props. */
+var DEFAULT_PROPS = {
+	selectedChipRender(choice, index, onClear, isDisabled, theme) {
+		const onClick = (event) => onClear && onClear(event, choice);
+		return /* @__PURE__ */ jsx(Chip, {
+			after: onClear && /* @__PURE__ */ jsx(Icon, {
+				icon: mdiClose,
+				size: Size.xxs
+			}),
+			isDisabled,
+			size: Size.s,
+			onAfterClick: onClick,
+			onClick,
+			theme,
+			children: choice
+		}, index);
+	},
+	selectedValueRender: (choice) => choice,
+	variant: SelectVariant.input
+};
+var SelectMultipleField = (props) => {
+	const defaultTheme = useTheme();
+	const { anchorRef, clearButtonProps, handleKeyboardNav, hasError, icon, id, isDisabled, isEmpty, isRequired, isValid, label, onClear, onInputClick, placeholder, selectedChipRender, selectedValueRender, theme = defaultTheme, value, variant, selectElementRef, ...forwardedProps } = props;
+	return /* @__PURE__ */ jsxs(Fragment, { children: [variant === SelectVariant.input && /* @__PURE__ */ jsxs(Fragment, { children: [label && /* @__PURE__ */ jsx("div", {
+		className: element("header"),
+		children: /* @__PURE__ */ jsx(InputLabel, {
+			htmlFor: id,
+			className: element("label"),
+			isRequired,
+			theme,
+			children: label
+		})
+	}), /* @__PURE__ */ jsxs("div", {
+		ref: mergeRefs(anchorRef, selectElementRef),
+		id,
+		className: element("wrapper"),
+		onClick: onInputClick,
+		onKeyDown: handleKeyboardNav,
+		tabIndex: isDisabled ? void 0 : 0,
+		"aria-disabled": isDisabled || void 0,
+		...forwardedProps,
+		children: [
+			icon && /* @__PURE__ */ jsx(Icon, {
+				className: element("input-icon"),
+				color: theme === Theme.dark ? "light" : void 0,
+				icon,
+				size: Size.xs
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: element("chips"),
+				children: !isEmpty && value.map((val, index) => selectedChipRender?.(val, index, onClear, isDisabled, theme))
+			}),
+			isEmpty && placeholder && /* @__PURE__ */ jsx("div", {
+				className: element("input-native", { placeholder: true }),
+				children: /* @__PURE__ */ jsx("span", { children: placeholder })
+			}),
+			(isValid || hasError) && /* @__PURE__ */ jsx("div", {
+				className: `${CLASSNAME}__input-validity`,
+				children: /* @__PURE__ */ jsx(Icon, {
+					icon: isValid ? mdiCheckCircle : mdiAlertCircle,
+					size: Size.xxs
+				})
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: `${CLASSNAME}__input-indicator`,
+				children: /* @__PURE__ */ jsx(Icon, {
+					icon: mdiMenuDown,
+					size: Size.s
+				})
+			})
+		]
+	})] }), variant === SelectVariant.chip && /* @__PURE__ */ jsxs(Chip, {
+		id,
+		isSelected: !isEmpty,
+		isDisabled,
+		after: /* @__PURE__ */ jsx(Icon, { icon: isEmpty ? mdiMenuDown : mdiCloseCircle }),
+		onAfterClick: isEmpty ? onInputClick : onClear,
+		onClick: onInputClick,
+		ref: mergeRefs(anchorRef, selectElementRef),
+		theme,
+		...forwardedProps,
+		children: [isEmpty && /* @__PURE__ */ jsx("span", { children: label }), !isEmpty && /* @__PURE__ */ jsxs("span", { children: [/* @__PURE__ */ jsx("span", { children: selectedValueRender?.(value[0]) }), value.length > 1 && /* @__PURE__ */ jsxs("span", { children: ["\xA0+", value.length - 1] })] })]
+	})] });
+};
+/**
+* SelectMultiple component.
+*
+* @deprecated use `SelectTextField` instead
+* @param  props Component props.
+* @param  ref   Component ref.
+* @return React element.
+*/
+var SelectMultiple = forwardRef((props, ref) => {
+	return WithSelectContext(SelectMultipleField, {
+		...DEFAULT_PROPS,
+		...props,
+		className: classNames.join(props.className, block({ "has-multiple": !props.isEmpty })),
+		isEmpty: props.value.length === 0,
+		isMultiple: true
+	}, ref);
+});
+SelectMultiple.displayName = COMPONENT_NAME;
+SelectMultiple.className = CLASSNAME;
+SelectMultiple.defaultProps = DEFAULT_PROPS;
+//#endregion
+export { SelectMultiple, SelectMultipleField };

package/_internal/components/select/WithSelectContext.js

@@ -0,0 +1,96 @@
+import { useId } from "../../hooks/useId.js";
+import { mergeRefs } from "../../utils/react/mergeRefs.js";
+import { useTheme } from "../../utils/theme/ThemeContext.js";
+import { useFocusTrap } from "../../hooks/useFocusTrap.js";
+import { Placement } from "../../packages/lumx-core/src/js/components/Popover/constants.js";
+import { Dropdown } from "../dropdown/Dropdown.js";
+import { InputHelper } from "../input-helper/InputHelper.js";
+import { useListenFocus } from "../../hooks/useListenFocus.js";
+import { Kind, Theme } from "@lumx/core/js/constants";
+import { useCallback, useRef } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { classNames } from "@lumx/core/js/utils";
+//#region src/components/select/WithSelectContext.tsx
+var { block, element } = classNames.bem("lumx-select");
+var WithSelectContext = (SelectElement, props, ref) => {
+	const defaultTheme = useTheme() || Theme.light;
+	const { children, className, focusElement, isMultiple, closeOnClick = !isMultiple, disabled, error, hasError, helper, id, isDisabled = disabled, isEmpty, isOpen, isRequired, isValid, label, onClear, onDropdownClose, onInfiniteScroll, onInputClick, placeholder, theme = defaultTheme, value, variant, ...forwardedProps } = props;
+	const generatedSelectId = useId();
+	const selectId = id || generatedSelectId;
+	const anchorRef = useRef(null);
+	const selectRef = useRef(null);
+	const dropdownRef = useRef(null);
+	const isFocus = useListenFocus(anchorRef);
+	const handleKeyboardNav = useCallback((evt) => {
+		if ((evt.key === "Enter" || evt.key === " " || evt.key === "ArrowDown") && onInputClick) {
+			evt.preventDefault();
+			onInputClick();
+		}
+	}, [onInputClick]);
+	const onClose = () => {
+		if (onDropdownClose) onDropdownClose();
+		anchorRef?.current?.blur();
+	};
+	useFocusTrap(isOpen && dropdownRef.current, focusElement?.current);
+	return /* @__PURE__ */ jsxs("div", {
+		ref: mergeRefs(ref, selectRef),
+		className: classNames.join(className, block({
+			"has-error": hasError,
+			"has-label": Boolean(label),
+			"has-placeholder": Boolean(placeholder),
+			"has-value": !isEmpty,
+			"is-disabled": isDisabled,
+			"is-empty": isEmpty,
+			"is-focus": isFocus,
+			"is-open": isOpen,
+			"is-valid": isValid,
+			[`theme-${theme}`]: Boolean(theme)
+		})),
+		children: [
+			/* @__PURE__ */ jsx(SelectElement, {
+				...forwardedProps,
+				anchorRef,
+				"aria-disabled": isDisabled,
+				handleKeyboardNav,
+				hasError,
+				isDisabled,
+				isEmpty,
+				isRequired,
+				isValid,
+				label,
+				placeholder,
+				id: selectId,
+				theme,
+				value,
+				variant,
+				onClear,
+				onInputClick
+			}),
+			/* @__PURE__ */ jsx(Dropdown, {
+				anchorRef,
+				closeOnClick,
+				closeOnClickAway: true,
+				closeOnEscape: true,
+				isOpen: !!isOpen,
+				placement: Placement.BOTTOM_START,
+				onClose,
+				onInfiniteScroll,
+				ref: dropdownRef,
+				children
+			}),
+			hasError && error && /* @__PURE__ */ jsx(InputHelper, {
+				className: element("helper"),
+				kind: Kind.error,
+				theme,
+				children: error
+			}),
+			helper && /* @__PURE__ */ jsx(InputHelper, {
+				className: element("helper"),
+				theme,
+				children: helper
+			})
+		]
+	});
+};
+//#endregion
+export { WithSelectContext };

package/_internal/components/select/constants.d.ts

@@ -0,0 +1,59 @@
+import { index_d_exports } from "../../utils/type/index.js";
+import { IconButtonProps } from "../button/IconButton.js";
+import { ReactNode, SyntheticEvent } from "react";
+
+//#region src/components/select/constants.d.ts
+/**
+ * Select variants.
+ */
+declare const SelectVariant: {
+  readonly input: "input";
+  readonly chip: "chip";
+};
+type SelectVariant = index_d_exports.ValueOf<typeof SelectVariant>;
+interface CoreSelectProps extends index_d_exports.GenericProps, index_d_exports.HasTheme {
+  /** Props to pass to the clear button (minus those already set by the Select props). If not specified, the button won't be displayed. */
+  clearButtonProps?: Pick<IconButtonProps, 'label'> & Omit<IconButtonProps, 'label' | 'onClick' | 'icon' | 'emphasis'>;
+  /** Whether the select (input variant) is displayed with error style or not. */
+  hasError?: boolean;
+  /** Error message. */
+  error?: string | ReactNode;
+  /** Helper text. */
+  helper?: string;
+  /** Whether the select should close on click. */
+  closeOnClick?: boolean;
+  /** Icon (SVG path). */
+  icon?: string;
+  /** Whether the component is disabled or not. */
+  isDisabled?: boolean;
+  /** Whether the component is required or not. */
+  isRequired?: boolean;
+  /** Whether the component is open or not. */
+  isOpen?: boolean;
+  /** Whether the select (input variant) is displayed with valid style or not. */
+  isValid?: boolean;
+  /** Label text. */
+  label?: string;
+  /** Placeholder input text. */
+  placeholder?: string;
+  /** Select variant. */
+  variant?: SelectVariant;
+  /** On clear callback. */
+  onClear?(event?: SyntheticEvent, value?: string): void;
+  /** On blur callback. */
+  onBlur?(): void;
+  /** On filter text change callback (with 500ms debounce). */
+  onFilter?(): void;
+  /** On input click callback (can be used for dropdown toggle). */
+  onInputClick?(): void;
+  /** On dropdown close callback. */
+  onDropdownClose?(): void;
+  /** On scroll end callback. */
+  onInfiniteScroll?(): void;
+  /** Render value function. Default: Renders the value as a string. */
+  selectedValueRender?(choice: string): ReactNode | string;
+  /** Children */
+  children?: React.ReactNode;
+}
+//#endregion
+export { CoreSelectProps, SelectVariant };

package/_internal/components/select/constants.js

@@ -0,0 +1,10 @@
+//#region src/components/select/constants.ts
+/**
+* Select variants.
+*/
+var SelectVariant = {
+	input: "input",
+	chip: "chip"
+};
+//#endregion
+export { SelectVariant };

package/_internal/components/select/index.d.ts

@@ -0,0 +1,3 @@
+import { SelectVariant } from "./constants.js";
+import { Select, SelectProps } from "./Select.js";
+import { SelectMultiple, SelectMultipleField, SelectMultipleProps } from "./SelectMultiple.js";

package/_internal/components/select-button/SelectButton.d.ts

@@ -0,0 +1,93 @@
+import { Comp } from "../../utils/type/Comp.js";
+import { ComponentRef } from "../../utils/type/ComponentRef.js";
+import { ReactToJSX } from "../../utils/type/ReactToJSX.js";
+import { ButtonProps } from "../button/Button.js";
+import { ComboboxButtonLabelDisplayMode } from "../../packages/lumx-core/src/js/components/Combobox/ComboboxButton.js";
+import { ComboboxPopoverProps } from "../combobox/ComboboxPopover.js";
+import { SelectButtonTranslations, SelectListStatus } from "../../packages/lumx-core/src/js/utils/select/types.js";
+import { SelectButtonProps as SelectButtonProps$1 } from "../../packages/lumx-core/src/js/components/SelectButton/index.js";
+import { GenericProps, NamedProps } from "@lumx/core/js/types";
+import React, { ElementType } from "react";
+
+//#region src/components/select-button/SelectButton.d.ts
+/** 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. */
+interface SelectButtonSelectProps<O> extends ReactToJSX<SelectButtonProps$1<O>, 'renderOption' | 'buttonProps' | 'value' | 'handleSelect' | 'listProps' | 'infiniteScrollOptions'> {
+  /** 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.ReactNode;
+}
+/**
+ * Forwarded trigger props for a given element `E`, minus the keys that the
+ * component manages internally.
+ */
+type TriggerProps<E extends ElementType> = Omit<NamedProps<React.ComponentProps<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 & {
+  /** 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?: SelectListStatus; /** 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 = 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'`).
+ */
+type SingleSelectButtonProps<O, E extends ElementType = typeof DefaultButton> = NamedProps<SelectButtonProps<O, E, 'single'>>;
+/**
+ * Multi-selection props (`selectionType: 'multiple'` is required to opt in).
+ */
+type MultipleSelectButtonProps<O, E extends ElementType = typeof DefaultButton> = NamedProps<SelectButtonProps<O, E, 'multiple'>>;
+//#endregion
+export { MultipleSelectButtonProps, SelectButtonProps, SingleSelectButtonProps };

package/_internal/components/select-button/SelectButton.js

@@ -0,0 +1,73 @@
+import { forwardRef } from "../../utils/react/forwardRef.js";
+import { Button } from "../button/Button.js";
+import { InfiniteScroll } from "../../utils/InfiniteScroll/InfiniteScroll.js";
+import { Combobox } from "../combobox/index.js";
+import { toggleSelection } from "../../packages/lumx-core/src/js/utils/select/toggleSelection.js";
+import { DEFAULT_PROPS, SelectButton as SelectButton$1 } from "../../packages/lumx-core/src/js/components/SelectButton/index.js";
+import { wrapRenderOption } from "../combobox/wrapRenderOption.js";
+import React, { useCallback, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+import { mdiMenuDown } from "@lumx/icons/esm/menu-down.js";
+//#region src/components/select-button/SelectButton.tsx
+/** Default trigger: LumX `Button` with the dropdown chevron pre-applied. */
+var DefaultButton = forwardRef((props, ref) => /* @__PURE__ */ jsx(Button, {
+	rightIcon: mdiMenuDown,
+	...props,
+	ref
+}));
+/**
+* A button trigger with a dropdown to select an option (single mode) or
+* options (multi mode) from a list. Polymorphic — pass `as` to customize the trigger element.
+*/
+var SelectButton = React.forwardRef((props, ref) => {
+	const { options, getOptionId, getOptionName, getOptionDescription, renderOption, getSectionId, renderSectionTitle, selectionType = DEFAULT_PROPS.selectionType, value, onChange, onLoadMore, onOpen, label, popoverProps, labelDisplayMode, listStatus, translations, as, ...buttonProps } = props;
+	const [listElement, setListElement] = useState(null);
+	const isMultiple = selectionType === "multiple";
+	const wrappedRenderOption = wrapRenderOption(renderOption);
+	const handleSelect = useCallback((selectedOption) => {
+		const next = toggleSelection(options, getOptionId, value, selectedOption?.value, isMultiple);
+		onChange?.(next);
+	}, [
+		getOptionId,
+		isMultiple,
+		onChange,
+		options,
+		value
+	]);
+	const buttonAs = as && as !== Button ? as : DefaultButton;
+	return SelectButton$1({
+		options,
+		getOptionId,
+		getOptionName,
+		getOptionDescription,
+		renderOption: wrappedRenderOption,
+		getSectionId,
+		renderSectionTitle,
+		value,
+		selectionType,
+		label,
+		labelDisplayMode,
+		buttonProps: {
+			...buttonProps,
+			as: buttonAs,
+			ref
+		},
+		popoverProps,
+		listProps: { ref: setListElement },
+		handleSelect,
+		listStatus,
+		onOpen,
+		translations,
+		onLoadMore,
+		infiniteScrollOptions: {
+			root: listElement,
+			rootMargin: "100px"
+		}
+	}, {
+		Combobox,
+		InfiniteScroll
+	});
+});
+SelectButton.displayName = "SelectButton";
+//#endregion
+export { SelectButton };

package/_internal/components/select-button/index.d.ts

@@ -0,0 +1,18 @@
+import { Comp } from "../../utils/type/Comp.js";
+import { ButtonProps } from "../button/Button.js";
+import { ComboboxOptionProps } from "../combobox/ComboboxOption.js";
+import { SelectButtonTranslations, SelectListStatus } from "../../packages/lumx-core/src/js/utils/select/types.js";
+import { MultipleSelectButtonProps, SelectButtonProps, SingleSelectButtonProps } from "./SelectButton.js";
+
+//#region src/components/select-button/index.d.ts
+/**
+ * SelectButton compound component.
+ */
+declare const SelectButton: {
+  <O, E extends import("react").ElementType = Comp<ButtonProps, HTMLButtonElement>, S extends "single" | "multiple" = "single">(props: SelectButtonProps<O, E, S>): React.ReactNode;
+  displayName?: string;
+} & {
+  /** Selectable option within the dropdown list. */Option: Comp<ComboboxOptionProps, HTMLLIElement>;
+};
+//#endregion
+export { SelectButton };

package/_internal/components/select-button/index.js

@@ -0,0 +1,11 @@
+import { ComboboxOption } from "../combobox/ComboboxOption.js";
+import { SelectButton as SelectButton$1 } from "./SelectButton.js";
+//#region src/components/select-button/index.ts
+/**
+* SelectButton compound component.
+*/
+var SelectButton = Object.assign(SelectButton$1, { 
+/** Selectable option within the dropdown list. */
+Option: ComboboxOption });
+//#endregion
+export { SelectButton };