@mezzanine-ui/react 1.0.0-beta.4 → 1.0.0-beta.6

package/Drawer/Drawer.js

@@ -1,22 +1,66 @@
 import { jsx, jsxs } from 'react/jsx-runtime';
-import { forwardRef, useState } from 'react';
+import { forwardRef, useState, useMemo } from 'react';
 import { drawerClasses } from '@mezzanine-ui/core/drawer';
 import { useDocumentEscapeKeyDown } from '../hooks/useDocumentEscapeKeyDown.js';
 import useTopStack from '../_internal/SlideFadeOverlay/useTopStack.js';
 import ClearActions from '../ClearActions/ClearActions.js';
 import Button from '../Button/Button.js';
+import Radio from '../Radio/Radio.js';
+import RadioGroup from '../Radio/RadioGroup.js';
 import { MOTION_EASING, MOTION_DURATION } from '@mezzanine-ui/system/motion';
 import Backdrop from '../Backdrop/Backdrop.js';
 import Slide from '../Transition/Slide.js';
 import cx from 'clsx';
 
 const Drawer = forwardRef((props, ref) => {
-    const { bottomGhostActionText, bottomOnGhostActionClick, bottomOnPrimaryActionClick, bottomOnSecondaryActionClick, bottomPrimaryActionText, bottomSecondaryActionText, children, className, container, disableCloseOnBackdropClick = false, disableCloseOnEscapeKeyDown = false, disablePortal, headerTitle, isBottomDisplay, isHeaderDisplay, onBackdropClick, onClose, open, size = 'medium', ...rest } = props;
+    const { bottomGhostActionDisabled, bottomGhostActionIcon, bottomGhostActionIconType, bottomGhostActionLoading, bottomGhostActionSize, bottomGhostActionText, bottomGhostActionVariant = 'base-ghost', bottomOnGhostActionClick, bottomOnPrimaryActionClick, bottomOnSecondaryActionClick, bottomPrimaryActionDisabled, bottomPrimaryActionIcon, bottomPrimaryActionIconType, bottomPrimaryActionLoading, bottomPrimaryActionSize, bottomPrimaryActionText, bottomPrimaryActionVariant = 'base-primary', bottomSecondaryActionDisabled, bottomSecondaryActionIcon, bottomSecondaryActionIconType, bottomSecondaryActionLoading, bottomSecondaryActionSize, bottomSecondaryActionText, bottomSecondaryActionVariant = 'base-secondary', children, className, container, controlBarAllRadioLabel, controlBarCustomButtonLabel = '全部已讀', controlBarDefaultValue, controlBarIsEmpty = false, controlBarOnCustomButtonClick, controlBarOnRadioChange, controlBarReadRadioLabel, controlBarShow = false, controlBarShowUnreadButton = false, controlBarUnreadRadioLabel, controlBarValue, disableCloseOnBackdropClick = false, disableCloseOnEscapeKeyDown = false, disablePortal, headerTitle, isBottomDisplay, isHeaderDisplay, onBackdropClick, onClose, open, renderControlBar: customRenderControlBar, size = 'medium', ...rest } = props;
     const [exited, setExited] = useState(true);
     /**
      * Escape keydown close: escape will only close the top drawer
      */
     const checkIsOnTheTop = useTopStack(open);
+    const renderControlBar = useMemo(() => {
+        // If custom renderControlBar is provided, use it
+        if (customRenderControlBar) {
+            return customRenderControlBar;
+        }
+        // Default control bar implementation
+        if (!controlBarShow) {
+            return undefined;
+        }
+        return () => {
+            const radios = [];
+            if (controlBarAllRadioLabel) {
+                radios.push(jsx(Radio, { type: "segment", value: "all", children: controlBarAllRadioLabel }, "all"));
+            }
+            if (controlBarReadRadioLabel) {
+                radios.push(jsx(Radio, { type: "segment", value: "read", children: controlBarReadRadioLabel }, "read"));
+            }
+            if (controlBarUnreadRadioLabel && controlBarShowUnreadButton) {
+                radios.push(jsx(Radio, { type: "segment", value: "unread", children: controlBarUnreadRadioLabel }, "unread"));
+            }
+            const hasRadios = radios.length > 0;
+            const hasButton = controlBarOnCustomButtonClick !== undefined;
+            // Don't render if neither radios nor button are provided
+            if (!hasRadios && !hasButton) {
+                return null;
+            }
+            return (jsxs("div", { className: cx(drawerClasses.controlBar, !hasRadios && hasButton && drawerClasses.controlBarButtonOnly), children: [hasRadios && (jsx(RadioGroup, { defaultValue: controlBarDefaultValue !== null && controlBarDefaultValue !== void 0 ? controlBarDefaultValue : 'all', onChange: controlBarOnRadioChange, size: "minor", type: "segment", value: controlBarValue, children: radios })), hasButton && (jsx(Button, { disabled: controlBarIsEmpty, onClick: controlBarOnCustomButtonClick, size: "minor", type: "button", variant: "base-ghost", children: controlBarCustomButtonLabel }))] }));
+        };
+    }, [
+        controlBarAllRadioLabel,
+        controlBarCustomButtonLabel,
+        controlBarDefaultValue,
+        controlBarIsEmpty,
+        controlBarOnCustomButtonClick,
+        controlBarOnRadioChange,
+        controlBarReadRadioLabel,
+        controlBarShow,
+        controlBarShowUnreadButton,
+        controlBarUnreadRadioLabel,
+        controlBarValue,
+        customRenderControlBar,
+    ]);
     useDocumentEscapeKeyDown(() => {
         if (!open || disableCloseOnEscapeKeyDown || !onClose) {
             return;
@@ -37,7 +81,7 @@ const Drawer = forwardRef((props, ref) => {
             }, easing: {
                 enter: MOTION_EASING.entrance,
                 exit: MOTION_EASING.exit,
-            }, in: open, onEntered: () => setExited(false), onExited: () => setExited(true), ref: ref, children: jsxs("div", { ...rest, className: cx(drawerClasses.host, drawerClasses.right, drawerClasses.size(size), className), children: [isHeaderDisplay && (jsxs("div", { className: drawerClasses.header, children: [headerTitle, jsx(ClearActions, { onClick: onClose })] })), jsx("div", { className: drawerClasses.content, children: children }), isBottomDisplay && (jsxs("div", { className: drawerClasses.bottom, children: [jsx("div", { children: bottomGhostActionText && bottomOnGhostActionClick && (jsx(Button, { onClick: bottomOnGhostActionClick, type: "button", variant: "base-ghost", children: bottomGhostActionText })) }), jsxs("div", { className: drawerClasses['bottom__actions'], children: [bottomSecondaryActionText && bottomOnSecondaryActionClick && (jsx(Button, { onClick: bottomOnSecondaryActionClick, type: "button", variant: "base-secondary", children: bottomSecondaryActionText })), bottomPrimaryActionText && bottomOnPrimaryActionClick && (jsx(Button, { onClick: bottomOnPrimaryActionClick, type: "button", variant: "base-primary", children: bottomPrimaryActionText }))] })] }))] }) }) }));
+            }, in: open, onEntered: () => setExited(false), onExited: () => setExited(true), ref: ref, children: jsxs("div", { ...rest, className: cx(drawerClasses.host, drawerClasses.right, drawerClasses.size(size), className), children: [isHeaderDisplay && (jsxs("div", { className: drawerClasses.header, children: [headerTitle, jsx(ClearActions, { onClick: onClose })] })), renderControlBar === null || renderControlBar === void 0 ? void 0 : renderControlBar(), jsx("div", { className: drawerClasses.content, children: children }), isBottomDisplay && (jsxs("div", { className: drawerClasses.bottom, children: [jsx("div", { children: bottomGhostActionText && bottomOnGhostActionClick && (jsx(Button, { disabled: bottomGhostActionDisabled, icon: bottomGhostActionIcon, iconType: bottomGhostActionIconType, loading: bottomGhostActionLoading, onClick: bottomOnGhostActionClick, size: bottomGhostActionSize, type: "button", variant: bottomGhostActionVariant, children: bottomGhostActionText })) }), jsxs("div", { className: drawerClasses['bottom__actions'], children: [bottomSecondaryActionText && bottomOnSecondaryActionClick && (jsx(Button, { disabled: bottomSecondaryActionDisabled, icon: bottomSecondaryActionIcon, iconType: bottomSecondaryActionIconType, loading: bottomSecondaryActionLoading, onClick: bottomOnSecondaryActionClick, size: bottomSecondaryActionSize, type: "button", variant: bottomSecondaryActionVariant, children: bottomSecondaryActionText })), bottomPrimaryActionText && bottomOnPrimaryActionClick && (jsx(Button, { disabled: bottomPrimaryActionDisabled, icon: bottomPrimaryActionIcon, iconType: bottomPrimaryActionIconType, loading: bottomPrimaryActionLoading, onClick: bottomOnPrimaryActionClick, size: bottomPrimaryActionSize, type: "button", variant: bottomPrimaryActionVariant, children: bottomPrimaryActionText }))] })] }))] }) }) }));
 });
 
 export { Drawer as default };

package/Dropdown/Dropdown.d.ts

@@ -163,12 +163,12 @@ export interface DropdownProps extends DropdownItemSharedProps {
      */
     emptyIcon?: IconDefinition;
     /**
-     * Whether to disable portal.
+     * Whether to enable portal.
      * This prop is only relevant when `inputPosition` is set to 'outside'.
      * Controls whether the dropdown content is rendered within the current hierarchy or portaled to the body.
-     * @default false
+     * @default true
      */
-    disablePortal?: boolean;
+    globalPortal?: boolean;
     /**
      * Callback fired when the dropdown list reaches the bottom.
      * Only fires when `maxHeight` is set and the list is scrollable.
@@ -179,5 +179,36 @@ export interface DropdownProps extends DropdownItemSharedProps {
      * Only fires when `maxHeight` is set and the list is scrollable.
      */
     onLeaveBottom?: () => void;
+    /**
+     * Callback fired when the dropdown list is scrolled.
+     * Receives the scroll event and computed scroll information.
+     */
+    onScroll?: (computed: {
+        scrollTop: number;
+        maxScrollTop: number;
+    }, target: HTMLDivElement) => void;
+    /**
+     * Whether to defer the initialization of OverlayScrollbars.
+     * This can improve initial render performance.
+     * @default true
+     */
+    scrollbarDefer?: boolean | object;
+    /**
+     * Whether to disable the custom scrollbar component.
+     * When false (default), Scrollbar component will be used when maxHeight is set.
+     * When true, falls back to native div scrolling (backward compatible).
+     * @default false
+     */
+    scrollbarDisabled?: boolean;
+    /**
+     * The maximum width of the scrollable container.
+     * Can be a CSS value string (e.g., '500px', '100%') or a number (treated as pixels).
+     */
+    scrollbarMaxWidth?: number | string;
+    /**
+     * Additional options to pass to OverlayScrollbars.
+     * @see https://kingsora.github.io/OverlayScrollbars/#!documentation/options
+     */
+    scrollbarOptions?: import('overlayscrollbars').PartialOptions;
 }
 export default function Dropdown(props: DropdownProps): import("react/jsx-runtime").JSX.Element;

package/Dropdown/Dropdown.js

@@ -3,7 +3,7 @@ import { jsxs, jsx } from 'react/jsx-runtime';
 import { useId, useMemo, useState, useRef, useCallback, useEffect, cloneElement, createElement } from 'react';
 import cx from 'clsx';
 import { dropdownClasses } from '@mezzanine-ui/core/dropdown/dropdown';
-import { size, offset, autoUpdate } from '@floating-ui/react-dom';
+import { size, offset } from '@floating-ui/react-dom';
 import { MOTION_EASING, MOTION_DURATION } from '@mezzanine-ui/system/motion';
 import { TransitionGroup } from 'react-transition-group';
 import Button from '../Button/Button.js';
@@ -14,7 +14,7 @@ import DropdownItem from './DropdownItem.js';
 import Popper from '../Popper/Popper.js';
 
 function Dropdown(props) {
-    const { activeIndex: activeIndexProp, id, children, options = [], type = 'default', maxHeight, disabled = false, showDropdownActions = false, actionCancelText, actionConfirmText, actionText, actionClearText, actionCustomButtonProps, showActionShowTopBar, isMatchInputValue = false, inputPosition = 'outside', placement = 'bottom', customWidth, sameWidth = false, listboxId: listboxIdProp, listboxLabel, onClose, onOpen, open: openProp, onVisibilityChange, onSelect, onActionConfirm, onActionCancel, onActionCustom, onActionClear, onItemHover, zIndex, status, loadingText, emptyText, emptyIcon, followText: followTextProp, disablePortal = false, onReachBottom, onLeaveBottom, mode, value, } = props;
+    const { activeIndex: activeIndexProp, id, children, options = [], type = 'default', maxHeight, disabled = false, showDropdownActions = false, actionCancelText, actionConfirmText, actionText, actionClearText, actionCustomButtonProps, showActionShowTopBar, isMatchInputValue = false, inputPosition = 'outside', placement = 'bottom', customWidth, sameWidth = false, listboxId: listboxIdProp, listboxLabel, onClose, onOpen, open: openProp, onVisibilityChange, onSelect, onActionConfirm, onActionCancel, onActionCustom, onActionClear, onItemHover, zIndex, status, loadingText, emptyText, emptyIcon, followText: followTextProp, globalPortal = true, onReachBottom, onLeaveBottom, onScroll, mode, value, scrollbarDefer, scrollbarDisabled, scrollbarMaxWidth, scrollbarOptions, } = props;
     const isInline = inputPosition === 'inside';
     const inputId = useId();
     const defaultListboxId = `${inputId}-listbox`;
@@ -101,9 +101,7 @@ function Dropdown(props) {
         if (!customWidth) {
             return null;
         }
-        const widthValue = typeof customWidth === 'number'
-            ? `${customWidth}px`
-            : customWidth;
+        const widthValue = typeof customWidth === 'number' ? `${customWidth}px` : customWidth;
         return {
             name: 'customWidth',
             fn: ({ elements }) => {
@@ -138,7 +136,9 @@ function Dropdown(props) {
             fn: ({ elements }) => {
                 const zIndexNum = typeof zIndexValue === 'number'
                     ? zIndexValue
-                    : (typeof zIndexValue === 'string' ? parseInt(zIndexValue, 10) || zIndexValue : 1);
+                    : typeof zIndexValue === 'string'
+                        ? parseInt(zIndexValue, 10) || zIndexValue
+                        : 1;
                 Object.assign(elements.floating.style, {
                     zIndex: zIndexNum,
                 });
@@ -177,28 +177,6 @@ function Dropdown(props) {
     const anchorRef = useRef(null);
     const popperRef = useRef(null);
     const popperControllerRef = useRef(null);
-    // Auto-update popper position when anchor element size changes
-    useEffect(() => {
-        if (!isOpen || isInline || !anchorRef.current || !popperControllerRef.current) {
-            return;
-        }
-        const update = popperControllerRef.current.update;
-        if (!update) {
-            return;
-        }
-        // Get floating element from controller refs
-        // Check refs exists before accessing nested properties
-        const refs = popperControllerRef.current.refs;
-        if (!refs) {
-            return;
-        }
-        const floatingElement = refs.floating.current;
-        if (!floatingElement) {
-            return;
-        }
-        const cleanup = autoUpdate(anchorRef.current, floatingElement, update);
-        return cleanup;
-    }, [isOpen, isInline]);
     // Extract combobox props logic to avoid duplication
     const getComboboxProps = useMemo(() => {
         const childWithRef = children;
@@ -231,6 +209,7 @@ function Dropdown(props) {
         onSelect,
         onReachBottom,
         onLeaveBottom,
+        onScroll,
         options,
         type,
         status,
@@ -239,6 +218,10 @@ function Dropdown(props) {
         emptyIcon,
         mode,
         value,
+        scrollbarDefer,
+        scrollbarDisabled,
+        scrollbarMaxWidth,
+        scrollbarOptions,
     }), [
         actionConfig,
         mergedActiveIndex,
@@ -252,6 +235,7 @@ function Dropdown(props) {
         onSelect,
         onReachBottom,
         onLeaveBottom,
+        onScroll,
         options,
         type,
         status,
@@ -260,6 +244,10 @@ function Dropdown(props) {
         emptyIcon,
         mode,
         value,
+        scrollbarDefer,
+        scrollbarDisabled,
+        scrollbarMaxWidth,
+        scrollbarOptions,
     ]);
     const triggerElement = useMemo(() => {
         const childWithRef = children;
@@ -353,7 +341,7 @@ function Dropdown(props) {
     }, [isInline, isOpen, setOpen]);
     return (jsxs("div", { id: id, ref: containerRef, className: cx(dropdownClasses.root, dropdownClasses.inputPosition(inputPosition)), children: [isInline && (jsxs(TransitionGroup, { component: null, children: [!isOpen && inlineTriggerElement && (createElement(Translate, { ...translateProps, from: translateFrom, key: "inline-trigger", in: true },
                         jsx("div", { children: inlineTriggerElement }))), isOpen && (createElement(Translate, { ...translateProps, from: translateFrom, key: "inline-list", in: true },
-                        jsx("div", { children: jsx(DropdownItem, { ...baseDropdownItemProps, headerContent: inlineTriggerElement }) })))] })), !isInline && (jsx(Popper, { ref: popperRef, anchor: anchorRef, className: dropdownClasses.popperWithPortal, controllerRef: popperControllerRef, open: isOpen, disablePortal: disablePortal, options: {
+                        jsx("div", { children: jsx(DropdownItem, { ...baseDropdownItemProps, headerContent: inlineTriggerElement }) })))] })), !isInline && (jsx(Popper, { ref: popperRef, anchor: anchorRef, className: dropdownClasses.popperWithPortal, controllerRef: popperControllerRef, open: isOpen, disablePortal: !globalPortal, options: {
                     placement: popoverPlacement,
                     middleware: [
                         offsetMiddleware,

package/Dropdown/DropdownItem.d.ts

@@ -1,6 +1,7 @@
 import { ReactNode } from 'react';
 import { DropdownItemSharedProps, DropdownOptionsByType, DropdownStatus as DropdownStatusType, DropdownType } from '@mezzanine-ui/core/dropdown/dropdown';
 import { type IconDefinition } from '@mezzanine-ui/icons';
+import type { PartialOptions } from 'overlayscrollbars';
 import { type DropdownActionProps } from './DropdownAction';
 export interface DropdownItemProps<T extends DropdownType | undefined = DropdownType> extends Omit<DropdownItemSharedProps, 'type'> {
     /**
@@ -83,5 +84,36 @@ export interface DropdownItemProps<T extends DropdownType | undefined = Dropdown
      * Only fires when `maxHeight` is set and the list is scrollable.
      */
     onLeaveBottom?: () => void;
+    /**
+     * Callback fired when the dropdown list is scrolled.
+     * Receives the scroll event and computed scroll information.
+     */
+    onScroll?: (computed: {
+        scrollTop: number;
+        maxScrollTop: number;
+    }, target: HTMLDivElement) => void;
+    /**
+     * Whether to defer the initialization of OverlayScrollbars.
+     * This can improve initial render performance.
+     * @default true
+     */
+    scrollbarDefer?: boolean | object;
+    /**
+     * Whether to disable the custom scrollbar component.
+     * When false (default), Scrollbar component will be used when maxHeight is set.
+     * When true, falls back to native div scrolling (backward compatible).
+     * @default false
+     */
+    scrollbarDisabled?: boolean;
+    /**
+     * The maximum width of the scrollable container.
+     * Can be a CSS value string (e.g., '500px', '100%') or a number (treated as pixels).
+     */
+    scrollbarMaxWidth?: number | string;
+    /**
+     * Additional options to pass to OverlayScrollbars.
+     * @see https://kingsora.github.io/OverlayScrollbars/#!documentation/options
+     */
+    scrollbarOptions?: PartialOptions;
 }
 export default function DropdownItem<T extends DropdownType | undefined = DropdownType>(props: DropdownItemProps<T>): import("react/jsx-runtime").JSX.Element;

package/Dropdown/DropdownItem.js

@@ -10,7 +10,19 @@ import DropdownAction from './DropdownAction.js';
 import DropdownItemCard from './DropdownItemCard.js';
 import DropdownStatus from './DropdownStatus.js';
 import { shortcutTextHandler } from './shortcutTextHandler.js';
+import Scrollbar from '../Scrollbar/Scrollbar.js';
 
+// Helper function to recursively get all descendant IDs from a tree option (excluding the option itself)
+function getAllDescendantIds(option) {
+    const ids = [];
+    if (option.children && option.children.length > 0) {
+        option.children.forEach((child) => {
+            ids.push(String(child.id));
+            ids.push(...getAllDescendantIds(child));
+        });
+    }
+    return ids;
+}
 /**
  * Limits DropdownOption array to a maximum depth, truncating extra children levels and showing error message if exceeded.
  * @param input - The original DropdownOption array
@@ -57,13 +69,16 @@ function truncateArrayDepth(input, maxDepth = 3, warn = true) {
     return truncate(input);
 }
 function DropdownItem(props) {
-    const { activeIndex, disabled = false, listboxId, listboxLabel, mode = 'single', options, value, type, maxHeight, actionConfig, onHover, onSelect, followText, headerContent, status, loadingText, emptyText, emptyIcon, onReachBottom, onLeaveBottom, } = props;
+    const { activeIndex, disabled = false, listboxId, listboxLabel, mode = 'single', options, value, type, maxHeight, actionConfig, onHover, onSelect, followText, headerContent, status, loadingText, emptyText, emptyIcon, onReachBottom, onLeaveBottom, onScroll, scrollbarDefer = true, scrollbarDisabled = false, scrollbarMaxWidth, scrollbarOptions, } = props;
     const optionsContent = truncateArrayDepth(options, 3);
     const listRef = useRef(null);
     const listWrapperRef = useRef(null);
+    const viewportRef = useRef(null);
+    const wasAtBottomRef = useRef(false);
     const [expandedNodes, setExpandedNodes] = useState(new Set());
     const hasActions = Boolean(actionConfig === null || actionConfig === void 0 ? void 0 : actionConfig.showActions);
     const hasHeader = Boolean(headerContent);
+    const shouldUseScrollbar = maxHeight && !scrollbarDisabled;
     // Use custom hook to measure element heights
     const [actionRef, actionHeight] = useElementHeight(hasActions && !!maxHeight);
     const [headerRef, headerHeight] = useElementHeight(hasHeader && !!maxHeight);
@@ -200,17 +215,39 @@ function DropdownItem(props) {
         });
         return { elements, nextIndex: currentIndex };
     };
+    const calculateNodeSelectionState = useCallback((option, selectedIds) => {
+        if (!option.children || option.children.length === 0) {
+            const isSelected = selectedIds.includes(String(option.id));
+            return { checked: isSelected, indeterminate: false };
+        }
+        // Get all descendant IDs (excluding the parent node itself)
+        const allDescendantIds = getAllDescendantIds(option);
+        const selectedDescendants = allDescendantIds.filter((id) => selectedIds.includes(id));
+        const totalDescendants = allDescendantIds.length;
+        if (totalDescendants === 0) {
+            // No descendants, check if parent itself is selected
+            const isSelected = selectedIds.includes(String(option.id));
+            return { checked: isSelected, indeterminate: false };
+        }
+        if (selectedDescendants.length === 0) {
+            return { checked: false, indeterminate: false };
+        }
+        if (selectedDescendants.length === totalDescendants) {
+            // All descendants are selected
+            return { checked: true, indeterminate: false };
+        }
+        // Some but not all descendants are selected
+        return { checked: false, indeterminate: true };
+    }, []);
     const renderTreeOptions = (optionList, depth, startIndex) => {
         let currentIndex = startIndex;
+        const selectedIds = Array.isArray(value) ? value.map((id) => String(id)) : value ? [String(value)] : [];
         const elements = (optionList !== null && optionList !== void 0 ? optionList : []).flatMap((option) => {
             var _a, _b, _c;
             currentIndex += 1;
             const optionIndex = currentIndex;
             const level = Math.min(depth, 2);
             const isActive = optionIndex === activeIndex;
-            const isSelected = Array.isArray(value)
-                ? value.includes(option.id)
-                : value === option.id;
             const hasChildren = Boolean(option.children && option.children.length > 0);
             const isExpanded = hasChildren && expandedNodes.has(option.id);
             let prependIcon = undefined;
@@ -221,13 +258,31 @@ function DropdownItem(props) {
             const shortcutText = option.shortcutText
                 ? option.shortcutText
                 : shortcutTextHandler((_a = option.shortcutKeys) !== null && _a !== void 0 ? _a : []);
-            const card = (jsx(DropdownItemCard, { active: isActive, checked: isSelected, disabled: disabled, id: `${listboxId}-option-${optionIndex}`, label: option.name, level: level, mode: mode, name: option.name, onClick: () => {
+            const selectionState = hasChildren && mode === 'multiple'
+                ? calculateNodeSelectionState(option, selectedIds)
+                : {
+                    checked: selectedIds.includes(String(option.id)),
+                    indeterminate: false,
+                };
+            const card = (jsx(DropdownItemCard, { active: isActive, checked: selectionState.checked, indeterminate: selectionState.indeterminate, disabled: disabled, id: `${listboxId}-option-${optionIndex}`, label: option.name, level: level, mode: mode, name: option.name, onClick: () => {
                     if (disabled)
                         return;
-                    if (hasChildren && type === 'tree') {
+                    if (hasChildren && type === 'tree' && mode === 'multiple' && option.showCheckbox) {
+                        toggleExpand(option.id);
+                    }
+                    else if (hasChildren && type === 'tree') {
                         toggleExpand(option.id);
                     }
                     else {
+                        // In `tree` + `multiple` mode, `DropdownItemCard` already triggers selection via
+                        // `onCheckedChange` when row is clicked (it toggles checked first, then calls `onClick`),
+                        // so calling `onSelect` here would cause it to fire twice for leaf nodes.
+                        if (!(type === 'tree' && mode === 'multiple')) {
+                            onSelect === null || onSelect === void 0 ? void 0 : onSelect(option);
+                        }
+                    }
+                }, onCheckedChange: () => {
+                    if (!disabled) {
                         onSelect === null || onSelect === void 0 ? void 0 : onSelect(option);
                     }
                 }, followText: followText, checkSite: checkSite, onMouseEnter: () => onHover === null || onHover === void 0 ? void 0 : onHover(optionIndex), prependIcon: prependIcon, showUnderline: (_b = option.showUnderline) !== null && _b !== void 0 ? _b : false, validate: (_c = option.validate) !== null && _c !== void 0 ? _c : 'default', appendContent: shortcutText }, option.id));
@@ -292,6 +347,10 @@ function DropdownItem(props) {
             maxHeight: `${availableHeight}px`,
         };
     }, [maxHeight, actionHeight, headerHeight]);
+    const getIsAtBottom = useCallback((viewport) => {
+        const { scrollTop, scrollHeight, clientHeight } = viewport;
+        return scrollTop + clientHeight >= scrollHeight - 1;
+    }, []);
     useEffect(() => {
         const listElement = listRef.current;
         if (!listElement || disabled) {
@@ -321,10 +380,17 @@ function DropdownItem(props) {
             listElement.removeEventListener('keydown', handleKeyDown);
         };
     }, [disabled, matchShortcut, onSelect, type, toggleExpand, visibleShortcutOptions]);
-    // Handle scroll to bottom detection
+    const handleViewportReady = useCallback((viewport) => {
+        viewportRef.current = viewport;
+        listWrapperRef.current = viewport;
+        wasAtBottomRef.current = getIsAtBottom(viewport);
+    }, [getIsAtBottom]);
     useEffect(() => {
+        if (shouldUseScrollbar) {
+            return;
+        }
         const listWrapperElement = listWrapperRef.current;
-        if (!listWrapperElement || !maxHeight || (!onReachBottom && !onLeaveBottom)) {
+        if (!listWrapperElement || !maxHeight || (!onReachBottom && !onLeaveBottom && !onScroll)) {
             return;
         }
         // Initialize wasAtBottom state by checking current position
@@ -335,6 +401,14 @@ function DropdownItem(props) {
         let wasAtBottom = checkInitialState();
         const handleScroll = () => {
             const { scrollTop, scrollHeight, clientHeight } = listWrapperElement;
+            const maxScrollTop = scrollHeight - clientHeight;
+            // Call onScroll callback if provided
+            if (onScroll) {
+                onScroll({
+                    scrollTop,
+                    maxScrollTop,
+                }, listWrapperElement);
+            }
             // Check if scrolled to bottom (with 1px threshold for rounding errors)
             const isAtBottom = scrollTop + clientHeight >= scrollHeight - 1;
             // Trigger onReachBottom when entering bottom state
@@ -351,9 +425,37 @@ function DropdownItem(props) {
         return () => {
             listWrapperElement.removeEventListener('scroll', handleScroll);
         };
-    }, [maxHeight, onReachBottom, onLeaveBottom]);
+    }, [maxHeight, onReachBottom, onLeaveBottom, onScroll, shouldUseScrollbar]);
+    const scrollbarEvents = useMemo(() => {
+        if (!shouldUseScrollbar || (!onReachBottom && !onLeaveBottom && !onScroll)) {
+            return undefined;
+        }
+        return {
+            scroll: (_instance, _event) => {
+                const viewport = viewportRef.current;
+                if (!viewport)
+                    return;
+                const { scrollTop, scrollHeight, clientHeight } = viewport;
+                const maxScrollTop = scrollHeight - clientHeight;
+                if (onScroll) {
+                    onScroll({
+                        scrollTop,
+                        maxScrollTop,
+                    }, viewport);
+                }
+                const isAtBottom = getIsAtBottom(viewport);
+                if (isAtBottom && !wasAtBottomRef.current) {
+                    onReachBottom === null || onReachBottom === void 0 ? void 0 : onReachBottom();
+                }
+                if (!isAtBottom && wasAtBottomRef.current) {
+                    onLeaveBottom === null || onLeaveBottom === void 0 ? void 0 : onLeaveBottom();
+                }
+                wasAtBottomRef.current = isAtBottom;
+            },
+        };
+    }, [getIsAtBottom, shouldUseScrollbar, onReachBottom, onLeaveBottom, onScroll]);
     return (jsxs("ul", { "aria-label": listboxLabel || (optionsContent.length === 0 ? 'Dropdown options' : undefined), className: dropdownClasses.list, id: listboxId, ref: listRef, role: "listbox", style: listStyle, tabIndex: -1, children: [hasHeader && (jsx("li", { className: dropdownClasses.listHeader, role: "presentation", ref: headerRef, children: jsx("div", { className: dropdownClasses.listHeaderInner, children: headerContent }) })), maxHeight
-                ? (jsx("div", { ref: listWrapperRef, className: dropdownClasses.listWrapper, style: listWrapperStyle, children: shouldShowStatus ? (jsx(DropdownStatus, { status: status, loadingText: loadingText, emptyText: emptyText, emptyIcon: emptyIcon })) : (renderedOptions) }))
+                ? (shouldUseScrollbar ? (jsx(Scrollbar, { className: dropdownClasses.listWrapper, defer: scrollbarDefer, disabled: false, events: scrollbarEvents, maxHeight: listWrapperStyle === null || listWrapperStyle === void 0 ? void 0 : listWrapperStyle.maxHeight, maxWidth: scrollbarMaxWidth, onViewportReady: handleViewportReady, options: scrollbarOptions, children: shouldShowStatus ? (jsx(DropdownStatus, { status: status, loadingText: loadingText, emptyText: emptyText, emptyIcon: emptyIcon })) : (renderedOptions) })) : (jsx("div", { ref: listWrapperRef, className: dropdownClasses.listWrapper, style: listWrapperStyle, children: shouldShowStatus ? (jsx(DropdownStatus, { status: status, loadingText: loadingText, emptyText: emptyText, emptyIcon: emptyIcon })) : (renderedOptions) })))
                 : shouldShowStatus ? (jsx(DropdownStatus, { status: status, loadingText: loadingText, emptyText: emptyText, emptyIcon: emptyIcon })) : (renderedOptions), hasActions && (jsx("div", { ref: actionRef, children: jsx(DropdownAction, { ...actionConfig }) }))] }));
 }
 

package/Dropdown/DropdownItemCard.d.ts

@@ -25,6 +25,11 @@ export interface DropdownItemCardProps {
      * When provided, the state is controlled externally.
      */
     checked?: boolean;
+    /**
+     * Whether the checkbox is in indeterminate state.
+     * Used in tree mode when some but not all children are selected.
+     */
+    indeterminate?: boolean;
     /**
      * Additional className for the list item.
      */

package/Dropdown/DropdownItemCard.js

@@ -10,7 +10,7 @@ import Icon from '../Icon/Icon.js';
 import Checkbox from '../Checkbox/Checkbox.js';
 
 function DropdownItemCard(props) {
-    const { active = false, appendIcon, appendContent, followText, id, label, level: levelProp, mode, name: _name, prependIcon, subTitle, validate, disabled, checked, defaultChecked, checkSite, onCheckedChange, onClick, className, onMouseEnter, showUnderline, } = props;
+    const { active = false, appendIcon, appendContent, followText, id, label, level: levelProp, mode, name: _name, prependIcon, subTitle, validate, disabled, checked, defaultChecked, indeterminate = false, checkSite, onCheckedChange, onClick, className, onMouseEnter, showUnderline, } = props;
     const cardLabel = label || '';
     const cardName = _name || cardLabel;
     const level = levelProp || 0;
@@ -111,7 +111,7 @@ function DropdownItemCard(props) {
                     [dropdownClasses.cardActive]: active || isChecked,
                     [dropdownClasses.cardDisabled]: disabled,
                     [dropdownClasses.cardDanger]: validate === 'danger',
-                }, className), id: id, role: "option", tabIndex: -1, onMouseEnter: onMouseEnter, onClick: handleClick, onKeyDown: handleKeyDown, children: jsxs("div", { className: dropdownClasses.cardContainer, children: [showPrependContent && (jsxs("div", { className: dropdownClasses.cardPrependContent, children: [prependIcon && jsx(Icon, { icon: prependIcon, color: iconColor }), checkSite === 'prefix' && mode === 'multiple' && (jsx(Checkbox, { checked: isChecked, disabled: disabled, onChange: handleCheckboxChange }))] })), jsxs("div", { className: dropdownClasses.cardBody, children: [cardLabel &&
+                }, className), id: id, role: "option", tabIndex: -1, onMouseEnter: onMouseEnter, onClick: handleClick, onKeyDown: handleKeyDown, children: jsxs("div", { className: dropdownClasses.cardContainer, children: [showPrependContent && (jsxs("div", { className: dropdownClasses.cardPrependContent, children: [prependIcon && jsx(Icon, { icon: prependIcon, color: iconColor }), checkSite === 'prefix' && mode === 'multiple' && (jsx(Checkbox, { checked: isChecked, disabled: disabled, indeterminate: indeterminate, onChange: handleCheckboxChange }))] })), jsxs("div", { className: dropdownClasses.cardBody, children: [cardLabel &&
                                     renderHighlightedText(labelParts, dropdownClasses.cardTitle, labelId), subTitleParts.length > 0 &&
                                     renderHighlightedText(subTitleParts, dropdownClasses.cardDescription)] }), showAppendContent && (jsxs("div", { className: dropdownClasses.cardAppendContent, children: [appendContent && (jsx(Typography, { color: "text-neutral-light", children: appendContent })), appendIcon && jsx(Icon, { icon: appendIcon, color: iconColor }), checkSite === 'suffix' && isChecked && (jsx(Icon, { icon: CheckedIcon, color: appendIconColor, size: 16 }))] }))] }) }), showUnderline && jsx("div", { className: dropdownClasses.cardUnderline })] }));
 }

package/Form/FormField.d.ts

@@ -1,4 +1,4 @@
-import { FormFieldCounterColor, FormFieldSize } from '@mezzanine-ui/core/form';
+import { ControlFieldSlotLayout, FormFieldCounterColor, FormFieldSize, LabelLayout } from '@mezzanine-ui/core/form';
 import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
 import { IconDefinition } from '@mezzanine-ui/icons';
 import { SeverityWithInfo } from '@mezzanine-ui/system/severity';
@@ -13,6 +13,12 @@ export interface FormFieldProps extends NativeElementPropsWithoutKeyAndRef<'div'
      * @default FormFieldCounterColor.INFO
      */
     counterColor?: FormFieldCounterColor;
+    /**
+     * The layout variant for the control field slot.
+     * Controls the visual styling and appearance of the input control area.
+     * @default ControlFieldSlotLayout.MAIN
+     */
+    controlFieldSlotLayout?: ControlFieldSlotLayout;
     /**
      * To control the field passed from children whether should be disabled.
      * The form message won't appear if disabled.
@@ -34,7 +40,7 @@ export interface FormFieldProps extends NativeElementPropsWithoutKeyAndRef<'div'
     /**
      * The label text for the form field.
      */
-    label: string;
+    label?: string;
     /**
      * The icon to display next to the label.
      * When provided, displays an icon that shows a tooltip on hover.
@@ -50,6 +56,12 @@ export interface FormFieldProps extends NativeElementPropsWithoutKeyAndRef<'div'
      * Typically used to show "(optional)" or similar text.
      */
     labelOptionalMarker?: string;
+    /**
+     * The layout variant for the label area.
+     * Controls the visual styling and appearance of the label.
+     * @default LabelLayout.HORIZONTAL_MAIN
+     */
+    labelLayout?: LabelLayout;
     /**
      * The name attribute for the form field.
      * Used to identify the field in form submissions and as htmlFor in the label.

package/Form/FormField.js

@@ -1,6 +1,6 @@
 import { jsx, jsxs } from 'react/jsx-runtime';
 import { forwardRef } from 'react';
-import { formFieldClasses, FormFieldCounterColor } from '@mezzanine-ui/core/form';
+import { ControlFieldSlotLayout, LabelLayout, formFieldClasses, FormFieldCounterColor } from '@mezzanine-ui/core/form';
 import { FormControlContext } from './FormControlContext.js';
 import FormHintText from './FormHintText.js';
 import FormLabel from './FormLabel.js';
@@ -10,7 +10,7 @@ import cx from 'clsx';
  * The React component for `mezzanine` form field.
  */
 const FormField = forwardRef(function FormField(props, ref) {
-    const { children, className, counter, counterColor, disabled = false, fullWidth = false, hintText, hintTextIcon, label, labelInformationIcon, labelInformationText, labelOptionalMarker, name, required = false, size, severity = 'info', ...rest } = props;
+    const { children, className, counter, counterColor, controlFieldSlotLayout = ControlFieldSlotLayout.MAIN, disabled = false, fullWidth = false, hintText, hintTextIcon, label, labelInformationIcon, labelInformationText, labelOptionalMarker, labelLayout = LabelLayout.HORIZONTAL_MAIN, name, required = false, size, severity = 'info', ...rest } = props;
     const formControl = {
         disabled,
         fullWidth,
@@ -20,7 +20,7 @@ const FormField = forwardRef(function FormField(props, ref) {
     return (jsx("div", { ...rest, ref: ref, className: cx(formFieldClasses.host, formFieldClasses.size(size), {
             [formFieldClasses.disabled]: disabled,
             [formFieldClasses.fullWidth]: fullWidth,
-        }, className), children: jsxs(FormControlContext.Provider, { value: formControl, children: [jsx(FormLabel, { className: formFieldClasses.labelArea, htmlFor: name, informationIcon: labelInformationIcon, informationText: labelInformationText, labelText: label, optionalMarker: labelOptionalMarker }), jsxs("div", { className: cx(formFieldClasses.dataEntry), children: [children, hintText || hintTextIcon || counter ? (jsxs("div", { className: cx(formFieldClasses.hintTextAndCounterArea, {
+        }, className), children: jsxs(FormControlContext.Provider, { value: formControl, children: [label && (jsx(FormLabel, { className: cx(formFieldClasses.labelArea, `${formFieldClasses.labelArea}--${labelLayout}`), htmlFor: name, informationIcon: labelInformationIcon, informationText: labelInformationText, labelText: label, optionalMarker: labelOptionalMarker })), jsxs("div", { className: cx(formFieldClasses.dataEntry), children: [jsx("div", { className: cx(`${formFieldClasses.controlFieldSlot}--${controlFieldSlotLayout}`), children: children }), hintText || hintTextIcon || counter ? (jsxs("div", { className: cx(formFieldClasses.hintTextAndCounterArea, {
                                 [formFieldClasses.hintTextAndCounterArea + '--align-right']: !(hintText || hintTextIcon) && counter,
                             }), children: [(hintText || hintTextIcon) && (jsx(FormHintText, { hintText: hintText, hintTextIcon: hintTextIcon, severity: severity })), counter && (jsx("span", { className: cx(formFieldClasses.counter, formFieldClasses.counterColor(counterColor || FormFieldCounterColor.INFO)), children: counter }))] })) : null] })] }) }));
 });

package/Form/useSelectValueControl.d.ts

@@ -2,19 +2,18 @@ import { MouseEvent } from 'react';
 import { SelectValue } from '../Select/typings';
 export interface UseSelectBaseValueControl {
     onClear?(e: MouseEvent<Element>): void;
-    onChange?(newOptions: SelectValue[] | SelectValue): any;
     onClose?(): void;
 }
 export type UseSelectMultipleValueControl = UseSelectBaseValueControl & {
     defaultValue?: SelectValue[];
     mode: 'multiple';
-    onChange?(newOptions: SelectValue[]): any;
+    onChange?(newOptions: SelectValue[]): void;
     value?: SelectValue[];
 };
 export type UseSelectSingleValueControl = UseSelectBaseValueControl & {
     defaultValue?: SelectValue;
     mode: 'single';
-    onChange?(newOption: SelectValue): any;
+    onChange?(newOption: SelectValue | null): void;
     value?: SelectValue | null;
 };
 export type UseSelectValueControl = UseSelectMultipleValueControl | UseSelectSingleValueControl;
@@ -22,7 +21,7 @@ export interface SelectBaseValueControl {
     onClear(e: MouseEvent<Element>): void;
 }
 export type SelectMultipleValueControl = SelectBaseValueControl & {
-    onChange: (v: SelectValue | null) => SelectValue[];
+    onChange: (v: SelectValue | SelectValue[] | null) => SelectValue[];
     value: SelectValue[];
 };
 export type SelectSingleValueControl = SelectBaseValueControl & {