@mezzanine-ui/react 1.3.0 → 1.4.0

package/Dropdown/Dropdown.d.ts

@@ -146,8 +146,12 @@ export interface DropdownProps extends DropdownItemSharedProps {
     sameWidth?: boolean;
     /**
      * Whether to enable floating-ui `flip` middleware.
-     * When `true`, the dropdown automatically flips to the opposite side
-     * (e.g. `bottom-start` → `top-start`) if it would overflow the viewport.
+     * When `true`, the dropdown automatically flips to the opposite side along
+     * the main axis (e.g. `bottom-start` → `top-start`) if it would overflow the
+     * viewport, and the enter transition slides from the resolved side. The flip
+     * is main-axis only (no `shift`/`crossAxis`), so a `sameWidth` menu stays
+     * horizontally aligned with its anchor — matching the `InputTriggerPopper`
+     * behavior used by the DatePicker/TimePicker menus.
      * Off by default to preserve existing placement behavior across consumers.
      * @default false
      */

package/Dropdown/Dropdown.js

@@ -10,20 +10,10 @@ import Button from '../Button/Button.js';
 import { useDocumentEvents } from '../hooks/useDocumentEvents.js';
 import Translate from '../Transition/Translate.js';
 import { composeRefs } from '../utils/composeRefs.js';
+import { getElementRef } from '../utils/getElementRef.js';
 import DropdownItem from './DropdownItem.js';
 import Popper from '../Popper/Popper.js';
 
-/**
- * Extracts ref from a ReactElement, supporting both React 18 and 19.
- * In React 18, ref is on the element itself; in React 19, ref is in props.
- */
-function getElementRef(element) {
-    var _a;
-    // React 19: ref is in props
-    const propsRef = (_a = element.props) === null || _a === void 0 ? void 0 : _a.ref;
-    // React 18: ref is on the element itself
-    return propsRef !== null && propsRef !== void 0 ? propsRef : element.ref;
-}
 /**
  * 下拉選單元件，以 `Button` 或 `Input` 作為觸發元素，點擊後展開選項列表。
  *
@@ -190,6 +180,9 @@ function Dropdown(props) {
         }
         return 'bottom';
     }, [inputPosition, placement]);
+    // Tracks the placement actually resolved by floating-ui. Only meaningful when
+    // `flip` is enabled, where it may differ from `popoverPlacement` after a flip.
+    const [resolvedPlacement, setResolvedPlacement] = useState(popoverPlacement);
     const customWidthMiddleware = useMemo(() => {
         if (!customWidth) {
             return null;
@@ -224,8 +217,11 @@ function Dropdown(props) {
     const flipMiddleware = useMemo(() => {
         if (!flip$1)
             return null;
+        // Main-axis flip only (bottom <-> top), aligned with `InputTriggerPopper`.
+        // No `shift`/`crossAxis` so a sameWidth menu keeps its horizontal alignment
+        // with the anchor instead of being pushed sideways.
         return flip({
-            fallbackStrategy: 'bestFit',
+            fallbackAxisSideDirection: 'end',
             padding: 8,
         });
     }, [flip$1]);
@@ -254,9 +250,12 @@ function Dropdown(props) {
         if (isInline) {
             return 'bottom';
         }
-        const placementBase = popoverPlacement.split('-')[0];
+        // When flip is enabled, follow the placement resolved by floating-ui so the
+        // enter transition slides from the correct side after a flip. Otherwise keep
+        // the static placement to preserve existing behavior for non-flip consumers.
+        const placementBase = (flip$1 ? resolvedPlacement : popoverPlacement).split('-')[0];
         return placementBase === 'top' ? 'top' : 'bottom';
-    }, [isInline, popoverPlacement]);
+    }, [flip$1, isInline, popoverPlacement, resolvedPlacement]);
     const setOpen = useCallback((next) => {
         const nextValue = typeof next === 'function'
             ? next(isOpen)
@@ -564,7 +563,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: !globalPortal, options: {
+                        jsx("div", { children: jsx(DropdownItem, { ...baseDropdownItemProps, headerContent: inlineTriggerElement }) })))] })), !isInline && (jsx(Popper, { ref: popperRef, anchor: anchorRef, className: dropdownClasses.popperWithPortal, controllerRef: popperControllerRef, onPlacementChange: setResolvedPlacement, open: isOpen, disablePortal: !globalPortal, options: {
                     placement: popoverPlacement,
                     middleware: [
                         offsetMiddleware,

package/Popper/Popper.d.ts

@@ -23,6 +23,13 @@ export interface PopperProps extends Pick<PortalProps, 'container' | 'disablePor
      * Provide `controllerRef` if you need access to `useFloating` results.
      */
     controllerRef?: Ref<PopperController>;
+    /**
+     * Callback fired whenever the resolved placement changes, including when
+     * floating-ui middleware (e.g. `flip`) flips the popper to the opposite
+     * side. Receives the actual placement after all middleware run, which may
+     * differ from `options.placement`.
+     */
+    onPlacementChange?: (placement: PopperPlacement) => void;
     /**
      * The portal element will show if open=true
      * @default false

package/Popper/Popper.js

@@ -10,7 +10,7 @@ import Portal from '../Portal/Portal.js';
 
 const Popper = forwardRef(function Popper(props, ref) {
     var _a, _b, _c, _d;
-    const { anchor, arrow: arrow$1, children, container, controllerRef, disablePortal, open = false, options, style, ...rest } = props;
+    const { anchor, arrow: arrow$1, children, container, controllerRef, disablePortal, onPlacementChange, open = false, options, style, ...rest } = props;
     const arrowRef = useRef(null);
     const anchorEl = getElement(anchor);
     const floatingReturn = useFloating({
@@ -42,6 +42,11 @@ const Popper = forwardRef(function Popper(props, ref) {
             update();
         }
     }, [open, update]);
+    // Notify consumers of the resolved placement so they can react to
+    // middleware-driven flips (e.g. adjusting enter-transition direction).
+    useEffect(() => {
+        onPlacementChange === null || onPlacementChange === void 0 ? void 0 : onPlacementChange(floatingReturn.placement);
+    }, [floatingReturn.placement, onPlacementChange]);
     // 計算箭頭的位置和旋轉角度
     const arrowX = (_b = floatingReturn.middlewareData.arrow) === null || _b === void 0 ? void 0 : _b.x;
     const arrowY = (_c = floatingReturn.middlewareData.arrow) === null || _c === void 0 ? void 0 : _c.y;

package/Select/Select.d.ts

@@ -54,6 +54,14 @@ export interface SelectBaseProps extends Omit<SelectTriggerProps, 'active' | 'in
      * The z-index of the dropdown.
      */
     dropdownZIndex?: number | string;
+    /**
+     * Whether to enable floating-ui `flip` middleware for the dropdown menu.
+     * When `true`, the menu flips from below to above the input (and back) along
+     * the main axis if it would overflow the viewport, keeping its width and
+     * horizontal alignment with the input. Forwarded to the underlying `Dropdown`.
+     * @default false
+     */
+    flip?: boolean;
     /**
      * Whether to enable portal for the dropdown.
      * @default true

package/Select/Select.js

@@ -45,7 +45,7 @@ import cx from 'clsx';
  */
 const Select = forwardRef(function Select(props, ref) {
     const { disabled: disabledFromFormControl, fullWidth: fullWidthFromFormControl, required: requiredFromFormControl, severity, } = useContext(FormControlContext) || {};
-    const { className, clearable = false, defaultValue, disabled = disabledFromFormControl || false, error = severity === 'error' || false, fullWidth = fullWidthFromFormControl || false, inputProps, inputRef, loading = false, loadingPosition = 'bottom', loadingText, menuMaxHeight, mode = 'single', onBlur, onChange: onChangeProp, onClear: onClearProp, onFocus, onLeaveBottom, onReachBottom, onScroll, options: optionsProp, placeholder = '', prefix, readOnly = false, renderValue, required = requiredFromFormControl || false, overflowStrategy, size, suffixActionIcon, type = 'default', value: valueProp, dropdownZIndex, globalPortal = true, } = props;
+    const { className, clearable = false, defaultValue, disabled = disabledFromFormControl || false, error = severity === 'error' || false, fullWidth = fullWidthFromFormControl || false, inputProps, inputRef, loading = false, loadingPosition = 'bottom', loadingText, menuMaxHeight, mode = 'single', onBlur, onChange: onChangeProp, onClear: onClearProp, onFocus, onLeaveBottom, onReachBottom, onScroll, options: optionsProp, placeholder = '', prefix, readOnly = false, renderValue, required = requiredFromFormControl || false, overflowStrategy, size, suffixActionIcon, type = 'default', value: valueProp, dropdownZIndex, flip = false, globalPortal = true, } = props;
     const dropdownStatus = loading
         ? 'loading'
         : undefined;
@@ -256,7 +256,7 @@ const Select = forwardRef(function Select(props, ref) {
         onChange,
         value,
     }), [onChange, value]);
-    return (jsx(SelectControlContext.Provider, { value: context, children: jsx("div", { ref: nodeRef, className: cx(selectClasses.host, fullWidth && selectClasses.hostFullWidth, mode && selectClasses.hostMode(mode)), children: jsx(Dropdown, { disabled: readOnly || disabled, globalPortal: globalPortal, loadingPosition: loadingPosition, loadingText: loadingText, maxHeight: menuMaxHeight, mode: mode, onLeaveBottom: onLeaveBottom, onReachBottom: onReachBottom, onScroll: onScroll, onSelect: handleDropdownSelect, onVisibilityChange: handleVisibilityChange, open: readOnly ? false : open, options: options, sameWidth: true, status: dropdownStatus, type: dropdownType, value: dropdownValue, zIndex: dropdownZIndex, children: jsx(SelectTrigger, { ref: composedRef, active: !readOnly && open, className: className, clearable: clearable, disabled: disabled, error: error, fullWidth: fullWidth, inputRef: inputRef, mode: mode, onTagClose: onChange, onClear: onClear, onKeyDown: onKeyDownTextField, prefix: prefix, readOnly: readOnly, ...(mode === 'single' && renderValue ? { renderValue } : {}), required: required, inputProps: resolvedInputProps, overflowStrategy: overflowStrategy, size: size, suffixActionIcon: suffixActionIcon, value: value === null ? undefined : value, placeholder: getPlaceholder() }) }) }) }));
+    return (jsx(SelectControlContext.Provider, { value: context, children: jsx("div", { ref: nodeRef, className: cx(selectClasses.host, fullWidth && selectClasses.hostFullWidth, mode && selectClasses.hostMode(mode)), children: jsx(Dropdown, { disabled: readOnly || disabled, flip: flip, globalPortal: globalPortal, loadingPosition: loadingPosition, loadingText: loadingText, maxHeight: menuMaxHeight, mode: mode, onLeaveBottom: onLeaveBottom, onReachBottom: onReachBottom, onScroll: onScroll, onSelect: handleDropdownSelect, onVisibilityChange: handleVisibilityChange, open: readOnly ? false : open, options: options, sameWidth: true, status: dropdownStatus, type: dropdownType, value: dropdownValue, zIndex: dropdownZIndex, children: jsx(SelectTrigger, { ref: composedRef, active: !readOnly && open, className: className, clearable: clearable, disabled: disabled, error: error, fullWidth: fullWidth, inputRef: inputRef, mode: mode, onTagClose: onChange, onClear: onClear, onKeyDown: onKeyDownTextField, prefix: prefix, readOnly: readOnly, ...(mode === 'single' && renderValue ? { renderValue } : {}), required: required, inputProps: resolvedInputProps, overflowStrategy: overflowStrategy, size: size, suffixActionIcon: suffixActionIcon, value: value === null ? undefined : value, placeholder: getPlaceholder() }) }) }) }));
 });
 
 export { Select as default };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mezzanine-ui/react",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "React components for mezzanine-ui",
   "author": "Mezzanine",
   "repository": {

package/utils/getElementRef.d.ts

@@ -0,0 +1,27 @@
+import { ReactElement, Ref } from 'react';
+/**
+ * Helper type to extract ref from a ReactElement.
+ * Models `ref` on the element itself, which is compatible with React 18 and 19.
+ */
+export type ReactElementWithRef<P, E extends Element = HTMLElement> = ReactElement<P> & {
+    ref?: Ref<E>;
+};
+/**
+ * Extracts ref from a ReactElement, supporting both React 18 and 19.
+ * In React 18, ref is on the element itself; in React 19, ref is in props.
+ *
+ * Reading the "wrong" location in dev mode triggers React warning getters:
+ *
+ * - React 18 installs a warning getter on `props.ref` when the element was
+ *   created with a ref — accessing it logs
+ *   "`ref` is not a prop. Trying to access it will result in `undefined` being returned."
+ * - React 19 installs a deprecation getter on `element.ref` when the element
+ *   was created with a ref — accessing it logs
+ *   "Accessing element.ref was removed in React 19."
+ *
+ * So instead of unconditionally reading `props.ref` first, detect the
+ * dev-mode warning getters (marked with `isReactWarning`) and read the ref
+ * from the location where it actually lives. Same approach as
+ * `getElementRef` in radix-ui/primitives.
+ */
+export declare function getElementRef<E extends Element = HTMLElement>(element: ReactElementWithRef<unknown, E>): Ref<E> | undefined;

package/utils/getElementRef.js

@@ -0,0 +1,52 @@
+/**
+ * Whether the given property getter is a React dev-mode warning getter.
+ * React marks them with `isReactWarning = true`
+ * (see `defineRefPropWarningGetter` in the React source).
+ */
+function isReactWarningGetter(getter) {
+    return (typeof getter === 'function' &&
+        Boolean(getter.isReactWarning));
+}
+/**
+ * Extracts ref from a ReactElement, supporting both React 18 and 19.
+ * In React 18, ref is on the element itself; in React 19, ref is in props.
+ *
+ * Reading the "wrong" location in dev mode triggers React warning getters:
+ *
+ * - React 18 installs a warning getter on `props.ref` when the element was
+ *   created with a ref — accessing it logs
+ *   "`ref` is not a prop. Trying to access it will result in `undefined` being returned."
+ * - React 19 installs a deprecation getter on `element.ref` when the element
+ *   was created with a ref — accessing it logs
+ *   "Accessing element.ref was removed in React 19."
+ *
+ * So instead of unconditionally reading `props.ref` first, detect the
+ * dev-mode warning getters (marked with `isReactWarning`) and read the ref
+ * from the location where it actually lives. Same approach as
+ * `getElementRef` in radix-ui/primitives.
+ */
+function getElementRef(element) {
+    var _a, _b, _c;
+    const props = element.props;
+    // React 18 dev mode: `props.ref` is a warning getter; the actual ref
+    // lives on the element itself.
+    const propsRefGetter = props
+        ? (_a = Object.getOwnPropertyDescriptor(props, 'ref')) === null || _a === void 0 ? void 0 : _a.get
+        : undefined;
+    if (isReactWarningGetter(propsRefGetter)) {
+        return element.ref;
+    }
+    // React 19 dev mode: `element.ref` may be a deprecation warning getter;
+    // the actual ref lives in props as a regular property.
+    const elementRefGetter = (_b = Object.getOwnPropertyDescriptor(element, 'ref')) === null || _b === void 0 ? void 0 : _b.get;
+    if (isReactWarningGetter(elementRefGetter)) {
+        return props === null || props === void 0 ? void 0 : props.ref;
+    }
+    // No warning getters (production builds, or no ref was given):
+    // prefer `props.ref` (React 19), fall back to `element.ref` (React 18).
+    // Safe on React 19 dev — its `element.ref` deprecation getter is only
+    // installed when a ref exists, in which case `props.ref` is returned here.
+    return (_c = props === null || props === void 0 ? void 0 : props.ref) !== null && _c !== void 0 ? _c : element.ref;
+}
+
+export { getElementRef };