@mezzanine-ui/react 1.0.4 → 1.2.0

package/COMPONENTS.md

@@ -150,37 +150,41 @@
 
 ## Utility（工具）
 
-| 元件                   | 匯入名稱                 | 說明                                                                                 |
-| ---------------------- | ------------------------ | ------------------------------------------------------------------------------------ |
-| Calendar               | `Calendar`               | 完整日曆元件，支援日/週/月/季/半年/年視圖切換                                        |
-| RangeCalendar          | `RangeCalendar`          | 範圍日曆，支援選取起始至結束日期範圍                                                 |
-| CalendarCell           | `CalendarCell`           | 日曆中的單一日期格子                                                                 |
-| CalendarConfigProvider | `CalendarConfigProvider` | 日曆全域設定提供者，設定語系與格式                                                   |
-| CalendarControls       | `CalendarControls`       | 日曆的月份/年份切換控制列                                                            |
-| CalendarDayOfWeek      | `CalendarDayOfWeek`      | 日曆的週幾標題列                                                                     |
-| CalendarDays           | `CalendarDays`           | 日曆的日期格子區域                                                                   |
-| CalendarHalfYears      | `CalendarHalfYears`      | 日曆的半年視圖                                                                       |
-| CalendarMonths         | `CalendarMonths`         | 日曆的月份視圖                                                                       |
-| CalendarQuarters       | `CalendarQuarters`       | 日曆的季度視圖                                                                       |
-| CalendarWeeks          | `CalendarWeeks`          | 日曆的週視圖                                                                         |
-| CalendarYears          | `CalendarYears`          | 日曆的年份視圖                                                                       |
-| Dropdown               | `Dropdown`               | 下拉選單面板，由 Select、AutoComplete、Cascader 等元件內部使用                       |
-| DropdownAction         | `DropdownAction`         | Dropdown 中的操作按鈕項目                                                            |
-| DropdownItem           | `DropdownItem`           | Dropdown 中的標準選項項目                                                            |
-| DropdownItemCard       | `DropdownItemCard`       | Dropdown 中的卡片式選項項目                                                          |
-| DropdownStatus         | `DropdownStatus`         | Dropdown 的狀態提示顯示（空狀態、載入中等）                                          |
-| Popper                 | `Popper`                 | 定位浮層元件，基於 Floating UI，Tooltip / Dropdown 的定位基底                        |
-| Portal                 | `Portal`                 | 將子元件渲染到指定 DOM 節點，Modal、Drawer 使用此元件脫離文件流                      |
-| TimePanel              | `TimePanel`              | 時間選取面板，包含時/分/秒的滾輪選取                                                 |
-| TimePanelColumn        | `TimePanelColumn`        | TimePanel 中的單一時間欄（時、分或秒）的滾輪列                                       |
-| Transition             | `Transition`             | 動畫過渡基底元件，提供 Collapse / Fade / Rotate / Scale / Slide / Translate 六種動畫 |
-| Collapse               | `Collapse`               | 收合展開動畫（高度過渡）                                                             |
-| Fade                   | `Fade`                   | 淡入淡出動畫                                                                         |
-| Rotate                 | `Rotate`                 | 旋轉動畫                                                                             |
-| Scale                  | `Scale`                  | 縮放動畫                                                                             |
-| Slide                  | `Slide`                  | 滑動動畫，Drawer 使用此元件進行進出場                                                |
-| Translate              | `Translate`              | 位移動畫                                                                             |
-| createNotifier         | `createNotifier`         | 工廠函式，建立通知管理器實例，用於指令式顯示 toast / 通知訊息                        |
+| 元件                           | 匯入名稱                         | 說明                                                                                                                                                        |
+| ------------------------------ | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Calendar                       | `Calendar`                       | 完整日曆元件，支援日/週/月/季/半年/年視圖切換                                                                                                               |
+| RangeCalendar                  | `RangeCalendar`                  | 範圍日曆，支援選取起始至結束日期範圍                                                                                                                        |
+| CalendarCell                   | `CalendarCell`                   | 日曆中的單一日期格子                                                                                                                                        |
+| CalendarConfigProvider         | `CalendarConfigProvider`         | 日曆全域設定提供者，設定語系與格式                                                                                                                          |
+| CalendarConfigProviderDayjs    | `CalendarConfigProviderDayjs`    | 預設綁定 dayjs 實作的 CalendarConfigProvider，sub-path entry `@mezzanine-ui/react/dayjs`                                                                    |
+| CalendarConfigProviderLuxon    | `CalendarConfigProviderLuxon`    | 預設綁定 luxon 實作的 CalendarConfigProvider，sub-path entry `@mezzanine-ui/react/luxon`                                                                    |
+| CalendarConfigProviderMoment   | `CalendarConfigProviderMoment`   | 預設綁定 moment 實作的 CalendarConfigProvider，sub-path entry `@mezzanine-ui/react/moment`                                                                  |
+| CalendarConfigProviderTemporal | `CalendarConfigProviderTemporal` | 預設綁定 JS-native Temporal 實作的 CalendarConfigProvider，sub-path entry `@mezzanine-ui/react/temporal`；Safari / Node 22 須先安裝 `@js-temporal/polyfill` |
+| CalendarControls               | `CalendarControls`               | 日曆的月份/年份切換控制列                                                                                                                                   |
+| CalendarDayOfWeek              | `CalendarDayOfWeek`              | 日曆的週幾標題列                                                                                                                                            |
+| CalendarDays                   | `CalendarDays`                   | 日曆的日期格子區域                                                                                                                                          |
+| CalendarHalfYears              | `CalendarHalfYears`              | 日曆的半年視圖                                                                                                                                              |
+| CalendarMonths                 | `CalendarMonths`                 | 日曆的月份視圖                                                                                                                                              |
+| CalendarQuarters               | `CalendarQuarters`               | 日曆的季度視圖                                                                                                                                              |
+| CalendarWeeks                  | `CalendarWeeks`                  | 日曆的週視圖                                                                                                                                                |
+| CalendarYears                  | `CalendarYears`                  | 日曆的年份視圖                                                                                                                                              |
+| Dropdown                       | `Dropdown`                       | 下拉選單面板，由 Select、AutoComplete、Cascader 等元件內部使用                                                                                              |
+| DropdownAction                 | `DropdownAction`                 | Dropdown 中的操作按鈕項目                                                                                                                                   |
+| DropdownItem                   | `DropdownItem`                   | Dropdown 中的標準選項項目                                                                                                                                   |
+| DropdownItemCard               | `DropdownItemCard`               | Dropdown 中的卡片式選項項目                                                                                                                                 |
+| DropdownStatus                 | `DropdownStatus`                 | Dropdown 的狀態提示顯示（空狀態、載入中等）                                                                                                                 |
+| Popper                         | `Popper`                         | 定位浮層元件，基於 Floating UI，Tooltip / Dropdown 的定位基底                                                                                               |
+| Portal                         | `Portal`                         | 將子元件渲染到指定 DOM 節點，Modal、Drawer 使用此元件脫離文件流                                                                                             |
+| TimePanel                      | `TimePanel`                      | 時間選取面板，包含時/分/秒的滾輪選取                                                                                                                        |
+| TimePanelColumn                | `TimePanelColumn`                | TimePanel 中的單一時間欄（時、分或秒）的滾輪列                                                                                                              |
+| Transition                     | `Transition`                     | 動畫過渡基底元件，提供 Collapse / Fade / Rotate / Scale / Slide / Translate 六種動畫                                                                        |
+| Collapse                       | `Collapse`                       | 收合展開動畫（高度過渡）                                                                                                                                    |
+| Fade                           | `Fade`                           | 淡入淡出動畫                                                                                                                                                |
+| Rotate                         | `Rotate`                         | 旋轉動畫                                                                                                                                                    |
+| Scale                          | `Scale`                          | 縮放動畫                                                                                                                                                    |
+| Slide                          | `Slide`                          | 滑動動畫，Drawer 使用此元件進行進出場                                                                                                                       |
+| Translate                      | `Translate`                      | 位移動畫                                                                                                                                                    |
+| createNotifier                 | `createNotifier`                 | 工廠函式，建立通知管理器實例，用於指令式顯示 toast / 通知訊息                                                                                               |
 
 ---
 

package/Calendar/CalendarConfigProviderTemporal.d.ts

@@ -0,0 +1,55 @@
+import { ReactNode } from 'react';
+import { CalendarLocaleValue } from '@mezzanine-ui/core/calendar';
+export type CalendarConfigProviderTemporalProps = {
+    children?: ReactNode;
+    defaultDateFormat?: string;
+    defaultTimeFormat?: string;
+    /**
+     * The unified locale for all calendar display and value processing.
+     * This determines the first day of week, month names, weekday names, etc.
+     * Use CalendarLocale enum for type-safe locale values.
+     * @example CalendarLocale.EN_US, CalendarLocale.ZH_TW, CalendarLocale.DE_DE
+     * @default CalendarLocale.EN_US
+     */
+    locale?: CalendarLocaleValue;
+};
+/**
+ * Pre-configured CalendarConfigProvider backed by the JS-native Temporal API.
+ *
+ * Requires `globalThis.Temporal` to be present **on the client** before any
+ * code imports `CalendarMethodsTemporal`. On runtimes that lack native
+ * support (Safari, Node 22), install `@js-temporal/polyfill` as a peer
+ * dependency.
+ *
+ * IMPORTANT: in Next.js App Router (and other RSC frameworks), default
+ * layouts are Server Components — registering the polyfill at module level
+ * in such a layout only runs on the server, leaving the browser without
+ * `globalThis.Temporal`. Use a Client Component wrapper instead. See the
+ * Calendar story docs for full setup examples (Vite/CRA vs App Router).
+ *
+ * @example
+ * ```tsx
+ * // app/temporal-polyfill.tsx (Client Component)
+ * 'use client';
+ * import { Temporal } from '@js-temporal/polyfill';
+ * (globalThis as { Temporal?: unknown }).Temporal = Temporal;
+ * export function TemporalPolyfill() { return null; }
+ *
+ * // app/layout.tsx
+ * import { TemporalPolyfill } from './temporal-polyfill';
+ * import { CalendarConfigProviderTemporal, CalendarLocale } from '@mezzanine-ui/react/temporal';
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html><body>
+ *       <TemporalPolyfill />
+ *       <CalendarConfigProviderTemporal locale={CalendarLocale.ZH_TW}>
+ *         {children}
+ *       </CalendarConfigProviderTemporal>
+ *     </body></html>
+ *   );
+ * }
+ * ```
+ */
+export declare function CalendarConfigProviderTemporal(props: CalendarConfigProviderTemporalProps): import("react/jsx-runtime").JSX.Element;
+export default CalendarConfigProviderTemporal;

package/Calendar/CalendarConfigProviderTemporal.js

@@ -0,0 +1,49 @@
+'use client';
+import { jsx } from 'react/jsx-runtime';
+import CalendarMethodsTemporal from '@mezzanine-ui/core/calendarMethodsTemporal';
+import CalendarConfigProvider from './CalendarContext.js';
+
+/**
+ * Pre-configured CalendarConfigProvider backed by the JS-native Temporal API.
+ *
+ * Requires `globalThis.Temporal` to be present **on the client** before any
+ * code imports `CalendarMethodsTemporal`. On runtimes that lack native
+ * support (Safari, Node 22), install `@js-temporal/polyfill` as a peer
+ * dependency.
+ *
+ * IMPORTANT: in Next.js App Router (and other RSC frameworks), default
+ * layouts are Server Components — registering the polyfill at module level
+ * in such a layout only runs on the server, leaving the browser without
+ * `globalThis.Temporal`. Use a Client Component wrapper instead. See the
+ * Calendar story docs for full setup examples (Vite/CRA vs App Router).
+ *
+ * @example
+ * ```tsx
+ * // app/temporal-polyfill.tsx (Client Component)
+ * 'use client';
+ * import { Temporal } from '@js-temporal/polyfill';
+ * (globalThis as { Temporal?: unknown }).Temporal = Temporal;
+ * export function TemporalPolyfill() { return null; }
+ *
+ * // app/layout.tsx
+ * import { TemporalPolyfill } from './temporal-polyfill';
+ * import { CalendarConfigProviderTemporal, CalendarLocale } from '@mezzanine-ui/react/temporal';
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html><body>
+ *       <TemporalPolyfill />
+ *       <CalendarConfigProviderTemporal locale={CalendarLocale.ZH_TW}>
+ *         {children}
+ *       </CalendarConfigProviderTemporal>
+ *     </body></html>
+ *   );
+ * }
+ * ```
+ */
+function CalendarConfigProviderTemporal(props) {
+    const { children, defaultDateFormat, defaultTimeFormat, locale } = props;
+    return (jsx(CalendarConfigProvider, { defaultDateFormat: defaultDateFormat, defaultTimeFormat: defaultTimeFormat, locale: locale, methods: CalendarMethodsTemporal, children: children }));
+}
+
+export { CalendarConfigProviderTemporal, CalendarConfigProviderTemporal as default };

package/Calendar/index.d.ts

@@ -10,6 +10,8 @@ export { default as CalendarConfigProviderMoment } from './CalendarConfigProvide
 export type { CalendarConfigProviderMomentProps } from './CalendarConfigProviderMoment';
 export { default as CalendarConfigProviderLuxon } from './CalendarConfigProviderLuxon';
 export type { CalendarConfigProviderLuxonProps } from './CalendarConfigProviderLuxon';
+export { default as CalendarConfigProviderTemporal } from './CalendarConfigProviderTemporal';
+export type { CalendarConfigProviderTemporalProps } from './CalendarConfigProviderTemporal';
 export type { CalendarYearsProps } from './CalendarYears';
 export { default as CalendarYears } from './CalendarYears';
 export type { CalendarQuartersProps } from './CalendarQuarters';

package/Calendar/index.js

@@ -5,6 +5,7 @@ export { default as CalendarConfigProvider, CalendarContext, useCalendarContext
 export { CalendarConfigProviderDayjs } from './CalendarConfigProviderDayjs.js';
 export { CalendarConfigProviderMoment } from './CalendarConfigProviderMoment.js';
 export { CalendarConfigProviderLuxon } from './CalendarConfigProviderLuxon.js';
+export { CalendarConfigProviderTemporal } from './CalendarConfigProviderTemporal.js';
 export { default as CalendarYears } from './CalendarYears.js';
 export { default as CalendarQuarters } from './CalendarQuarters.js';
 export { default as CalendarHalfYears } from './CalendarHalfYears.js';

package/Dropdown/Dropdown.d.ts

@@ -144,6 +144,14 @@ export interface DropdownProps extends DropdownItemSharedProps {
      * @default false
      */
     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.
+     * Off by default to preserve existing placement behavior across consumers.
+     * @default false
+     */
+    flip?: boolean;
     /**
      * If true, display a bar at the top of the dropdown action area.
      * @default false

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 } from '@floating-ui/react-dom';
+import { size, offset, flip } 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';
@@ -72,7 +72,7 @@ function getElementRef(element) {
  * @see {@link AutoComplete} 具備自動補全功能的輸入元件
  */
 function Dropdown(props) {
-    const { activeIndex: activeIndexProp, keyboardActiveIndex: keyboardActiveIndexProp, id, children, options = [], type = 'default', toggleCheckedOnClick, maxHeight, minWidth, disabled = false, showDropdownActions = false, actionCancelText, actionConfirmText, actionText, actionClearText, actionCustomButtonProps, showActionShowTopBar, isMatchInputValue = false, inputPosition = 'outside', placement = 'bottom-start', customWidth, sameWidth = false, listboxId: listboxIdProp, listboxLabel, onClose, onOpen, open: openProp, onVisibilityChange, onSelect, onActionConfirm, onActionCancel, onActionCustom, onActionClear, onItemHover, zIndex, status, loadingText, emptyText, emptyIcon, loadingPosition = 'full', followText: followTextProp, globalPortal = true, onReachBottom, onLeaveBottom, onScroll, mode, value, scrollbarDefer, scrollbarDisabled, scrollbarMaxWidth, scrollbarOptions, } = props;
+    const { activeIndex: activeIndexProp, keyboardActiveIndex: keyboardActiveIndexProp, id, children, options = [], type = 'default', toggleCheckedOnClick, maxHeight, minWidth, disabled = false, showDropdownActions = false, actionCancelText, actionConfirmText, actionText, actionClearText, actionCustomButtonProps, showActionShowTopBar, isMatchInputValue = false, inputPosition = 'outside', placement = 'bottom-start', customWidth, sameWidth = false, flip: flip$1 = false, listboxId: listboxIdProp, listboxLabel, onClose, onOpen, open: openProp, onVisibilityChange, onSelect, onActionConfirm, onActionCancel, onActionCustom, onActionClear, onItemHover, zIndex, status, loadingText, emptyText, emptyIcon, loadingPosition = 'full', 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`;
@@ -221,6 +221,14 @@ function Dropdown(props) {
     const offsetMiddleware = useMemo(() => {
         return offset({ mainAxis: 4 });
     }, []);
+    const flipMiddleware = useMemo(() => {
+        if (!flip$1)
+            return null;
+        return flip({
+            fallbackStrategy: 'bestFit',
+            padding: 8,
+        });
+    }, [flip$1]);
     // Set z-index for popper only when explicitly provided via the `zIndex` prop.
     // When not provided, do NOT apply any inline z-index so that elements inside
     // the portal stack purely by DOM order — this ensures Modals opened from
@@ -560,6 +568,7 @@ function Dropdown(props) {
                     placement: popoverPlacement,
                     middleware: [
                         offsetMiddleware,
+                        ...(flipMiddleware ? [flipMiddleware] : []),
                         ...(zIndexMiddleware ? [zIndexMiddleware] : []),
                         ...(customWidthMiddleware ? [customWidthMiddleware] : []),
                         ...(sameWidthMiddleware ? [sameWidthMiddleware] : []),

package/Input/SelectButton/SelectButton.d.ts

@@ -3,6 +3,11 @@ import { DropdownOption } from '@mezzanine-ui/core/dropdown/dropdown';
 import { PopperPlacement } from '../../Popper';
 import { NativeElementPropsWithoutKeyAndRef } from '../../utils/jsx-types';
 export interface SelectButtonProps extends Omit<NativeElementPropsWithoutKeyAndRef<'button'>, 'disabled' | 'onSelect' | 'type' | 'selectedValue'> {
+    /**
+     * Whether clicking an option should automatically close the dropdown.
+     * @default true
+     */
+    closeOnSelect?: boolean;
     /**
      * Whether the select button is disabled.
      */

package/Input/SelectButton/SelectButton.js

@@ -10,24 +10,24 @@ import Icon from '../../Icon/Icon.js';
 import cx from 'clsx';
 
 const SelectButton = forwardRef(function SelectButton(props, ref) {
-    const { className, disabled, dropdownMaxHeight = 114, dropdownPlacement = 'bottom-start', dropdownWidth = 120, onSelect, options = [], size = 'main', value, ...rest } = props;
+    const { className, closeOnSelect = true, disabled, dropdownMaxHeight = 114, dropdownPlacement = 'bottom-start', dropdownWidth = 120, onSelect, options = [], size = 'main', value, ...rest } = props;
     const [open, setOpen] = useState(false);
-    const handleOpen = useCallback(() => {
-        if (!disabled) {
-            setOpen(true);
-        }
+    const handleVisibilityChange = useCallback((next) => {
+        if (disabled && next)
+            return;
+        setOpen(next);
     }, [disabled]);
-    const handleClose = useCallback(() => {
-        setOpen(false);
-    }, []);
     const handleSelect = useCallback((option) => {
         onSelect === null || onSelect === void 0 ? void 0 : onSelect(option.id);
-    }, [onSelect]);
+        if (closeOnSelect) {
+            setOpen(false);
+        }
+    }, [closeOnSelect, onSelect]);
     const dropdownOptions = options.map((option) => ({
         ...option,
         ...(option.id === value ? { checkSite: 'suffix' } : {}),
     }));
-    return (jsx(Dropdown, { customWidth: dropdownWidth, disabled: disabled, maxHeight: dropdownMaxHeight, onClose: handleClose, onOpen: handleOpen, onSelect: handleSelect, options: dropdownOptions, placement: dropdownPlacement, value: value, children: jsxs("button", { ref: ref, type: "button", disabled: disabled, className: cx(inputSelectButtonClasses.host, disabled && inputSelectButtonClasses.disabled, size === 'main' ? inputSelectButtonClasses.main : inputSelectButtonClasses.sub, className), title: value, ...rest, children: [jsx("span", { className: inputSelectButtonClasses.text, children: value }), jsx(Rotate, { in: open, duration: MOTION_DURATION.fast, easing: MOTION_EASING.standard, children: jsx(Icon, { className: inputSelectButtonClasses.icon, icon: ChevronDownIcon, size: 16 }) })] }) }));
+    return (jsx(Dropdown, { customWidth: dropdownWidth, disabled: disabled, maxHeight: dropdownMaxHeight, onSelect: handleSelect, onVisibilityChange: handleVisibilityChange, open: open, options: dropdownOptions, placement: dropdownPlacement, value: value, children: jsxs("button", { ref: ref, type: "button", disabled: disabled, className: cx(inputSelectButtonClasses.host, disabled && inputSelectButtonClasses.disabled, size === 'main' ? inputSelectButtonClasses.main : inputSelectButtonClasses.sub, className), title: value, ...rest, children: [jsx("span", { className: inputSelectButtonClasses.text, children: value }), jsx(Rotate, { in: open, duration: MOTION_DURATION.fast, easing: MOTION_EASING.standard, children: jsx(Icon, { className: inputSelectButtonClasses.icon, icon: ChevronDownIcon, size: 16 }) })] }) }));
 });
 
 export { SelectButton as default };

package/Pagination/PaginationPageSize.js

@@ -25,7 +25,7 @@ const PaginationPageSize = forwardRef((props, ref) => {
         onChange === null || onChange === void 0 ? void 0 : onChange(Number(option.id));
         setOpen(false);
     };
-    return (jsxs("div", { ...rest, ref: ref, className: cx(paginationPageSizeClasses.host, className), children: [label ? (jsx(Typography, { component: "div", ellipsis: true, variant: "label-primary", children: label })) : null, jsx(Dropdown, { disabled: disabled, minWidth: 0, onSelect: dropDownOnSelect, onVisibilityChange: setOpen, open: open, options: selectOptions, sameWidth: true, value: currentValue === null || currentValue === void 0 ? void 0 : currentValue.id, children: jsx(SelectTrigger, { className: paginationPageSizeClasses.select, disabled: disabled, size: "sub", value: currentValue }) })] }));
+    return (jsxs("div", { ...rest, ref: ref, className: cx(paginationPageSizeClasses.host, className), children: [label ? (jsx(Typography, { component: "div", ellipsis: true, variant: "label-primary", children: label })) : null, jsx(Dropdown, { disabled: disabled, flip: true, minWidth: 0, onSelect: dropDownOnSelect, onVisibilityChange: setOpen, open: open, options: selectOptions, sameWidth: true, value: currentValue === null || currentValue === void 0 ? void 0 : currentValue.id, children: jsx(SelectTrigger, { className: paginationPageSizeClasses.select, disabled: disabled, size: "sub", value: currentValue }) })] }));
 });
 
 export { PaginationPageSize as default };

package/Picker/getFocusableElements.d.ts

@@ -0,0 +1,3 @@
+export declare function getFocusableElements(container: HTMLElement | null): HTMLElement[];
+export declare function getNextTabbableAfter(element: HTMLElement, skipContainer?: HTMLElement | null): HTMLElement | null;
+export declare function getPreviousTabbableBefore(element: HTMLElement): HTMLElement | null;

package/Picker/getFocusableElements.js

@@ -0,0 +1,70 @@
+const FOCUSABLE_SELECTOR = [
+    'a[href]',
+    'area[href]',
+    'button:not([disabled])',
+    'input:not([disabled]):not([type="hidden"])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    'iframe',
+    'object',
+    'embed',
+    'audio[controls]',
+    'video[controls]',
+    '[contenteditable]:not([contenteditable="false"])',
+    '[tabindex]:not([tabindex="-1"])',
+].join(',');
+function isVisible(element) {
+    var _a, _b;
+    if (element.hidden)
+        return false;
+    const style = (_b = (_a = element.ownerDocument) === null || _a === void 0 ? void 0 : _a.defaultView) === null || _b === void 0 ? void 0 : _b.getComputedStyle(element);
+    if (!style)
+        return true;
+    return style.visibility !== 'hidden' && style.display !== 'none';
+}
+function getFocusableElements(container) {
+    if (!container)
+        return [];
+    const nodes = container.querySelectorAll(FOCUSABLE_SELECTOR);
+    const result = [];
+    for (const node of Array.from(nodes)) {
+        if (node.getAttribute('aria-hidden') === 'true')
+            continue;
+        if (!isVisible(node))
+            continue;
+        result.push(node);
+    }
+    return result;
+}
+function getNextTabbableAfter(element, skipContainer) {
+    const doc = element.ownerDocument;
+    const all = getFocusableElements(doc.body);
+    for (const node of all) {
+        if (node === element || element.contains(node))
+            continue;
+        if (skipContainer &&
+            (node === skipContainer || skipContainer.contains(node)))
+            continue;
+        const position = element.compareDocumentPosition(node);
+        if (position & Node.DOCUMENT_POSITION_FOLLOWING) {
+            return node;
+        }
+    }
+    return null;
+}
+function getPreviousTabbableBefore(element) {
+    const doc = element.ownerDocument;
+    const all = getFocusableElements(doc.body);
+    let previous = null;
+    for (const node of all) {
+        if (node === element || element.contains(node))
+            continue;
+        const position = element.compareDocumentPosition(node);
+        if (position & Node.DOCUMENT_POSITION_PRECEDING) {
+            previous = node;
+        }
+    }
+    return previous;
+}
+
+export { getFocusableElements, getNextTabbableAfter, getPreviousTabbableBefore };

package/Picker/usePickerDocumentEventClose.js

@@ -1,27 +1,141 @@
+import { useRef } from 'react';
 import { useClickAway } from '../hooks/useClickAway.js';
 import { useDocumentEscapeKeyDown } from '../hooks/useDocumentEscapeKeyDown.js';
-import { useTabKeyClose } from './useTabKeyClose.js';
+import { useDocumentTabKeyDown } from '../hooks/useDocumentTabKeyDown.js';
+import { useIsomorphicLayoutEffect } from '../hooks/useIsomorphicLayoutEffect.js';
+import { getFocusableElements, getNextTabbableAfter, getPreviousTabbableBefore } from './getFocusableElements.js';
 
 function usePickerDocumentEventClose({ anchorRef, lastElementRefInFlow, onClose, onChangeClose, open, popperRef, }) {
-    useClickAway(() => {
-        if (!open) {
+    /**
+     * Mirror the latest values into refs so the document-level event handlers
+     * (which are installed once and only re-installed when deps change) always
+     * read the freshest props rather than a closure captured at install time.
+     */
+    const openRef = useRef(open);
+    const onCloseRef = useRef(onClose);
+    const onChangeCloseRef = useRef(onChangeClose);
+    useIsomorphicLayoutEffect(() => {
+        openRef.current = open;
+        onCloseRef.current = onClose;
+        onChangeCloseRef.current = onChangeClose;
+    });
+    useClickAway(() => (event) => {
+        var _a;
+        if (!openRef.current)
             return;
+        if (!((_a = popperRef.current) === null || _a === void 0 ? void 0 : _a.contains(event.target))) {
+            onChangeCloseRef.current();
         }
-        return (event) => {
-            var _a;
-            if (!((_a = popperRef.current) === null || _a === void 0 ? void 0 : _a.contains(event.target))) {
-                onChangeClose();
-            }
-        };
-    }, anchorRef, [open, onClose]);
-    /** Close popper when escape key down */
+    }, anchorRef, []);
+    /**
+     * Close popper on Escape and return focus to the trigger input so the
+     * user does not lose their place in the page tab order.
+     */
     useDocumentEscapeKeyDown(() => () => {
-        if (open) {
-            onClose();
+        var _a;
+        if (!openRef.current)
+            return;
+        onCloseRef.current();
+        const popper = popperRef.current;
+        const active = document.activeElement;
+        if (popper && active && popper.contains(active)) {
+            (_a = lastElementRefInFlow.current) === null || _a === void 0 ? void 0 : _a.focus();
         }
-    }, [open, onClose]);
-    /** Close popper when tab key down */
-    useTabKeyClose(onChangeClose, lastElementRefInFlow, [onChangeClose]);
+    }, [lastElementRefInFlow, popperRef]);
+    /**
+     * Keyboard navigation across the trigger input and the portalled popper.
+     *
+     * The popper is rendered into document.body via Portal, so the natural
+     * Tab order skips it entirely. We bridge the trigger and the popper as
+     * a logical sequence:
+     *
+     *   - Tab from trigger input  → first focusable inside popper  (handled by
+     *     the direct trigger listener below, which uses `stopPropagation` so
+     *     this document-level handler does not run again for that case)
+     *   - Shift+Tab from trigger  → close popper                  (same)
+     *   - Tab from last popper    → close + focus next tab stop after anchor
+     *   - Shift+Tab from first    → return focus to trigger input
+     *
+     * Other Tabs inside the popper fall through to the browser's default
+     * focus traversal, so users can walk through calendar buttons, footer
+     * actions, etc. with the regular keyboard.
+     */
+    useDocumentTabKeyDown(() => (event) => {
+        var _a;
+        if (!openRef.current)
+            return;
+        const popper = popperRef.current;
+        const anchor = anchorRef.current;
+        const trigger = lastElementRefInFlow.current;
+        if (!popper || !anchor)
+            return;
+        const active = document.activeElement;
+        if (!active || !popper.contains(active))
+            return;
+        const focusables = getFocusableElements(popper);
+        if (focusables.length === 0)
+            return;
+        const first = focusables[0];
+        const last = focusables[focusables.length - 1];
+        if (!event.shiftKey && active === last) {
+            event.preventDefault();
+            onChangeCloseRef.current();
+            const next = getNextTabbableAfter(anchor, popper);
+            if (next) {
+                next.focus();
+            }
+            else {
+                trigger === null || trigger === void 0 ? void 0 : trigger.blur();
+            }
+            return;
+        }
+        if (event.shiftKey && active === first) {
+            event.preventDefault();
+            if (trigger) {
+                trigger.focus();
+            }
+            else {
+                onChangeCloseRef.current();
+                (_a = getPreviousTabbableBefore(anchor)) === null || _a === void 0 ? void 0 : _a.focus();
+            }
+        }
+    }, [anchorRef, popperRef, lastElementRefInFlow]);
+    /**
+     * Direct keydown listener on the trigger element for the Tab → popper
+     * bridge. Binding directly on the trigger (instead of the document) is
+     * more reliable: it still fires when the picker lives inside a Modal or
+     * focus trap that stops keydown propagation before it reaches document.
+     */
+    useIsomorphicLayoutEffect(() => {
+        const trigger = lastElementRefInFlow.current;
+        if (!trigger)
+            return;
+        const handleKeyDown = (event) => {
+            if (event.key !== 'Tab')
+                return;
+            if (!openRef.current)
+                return;
+            const popper = popperRef.current;
+            if (!popper)
+                return;
+            if (event.shiftKey) {
+                onChangeCloseRef.current();
+                return;
+            }
+            const focusables = getFocusableElements(popper);
+            if (focusables.length === 0) {
+                onChangeCloseRef.current();
+                return;
+            }
+            event.preventDefault();
+            event.stopPropagation();
+            focusables[0].focus();
+        };
+        trigger.addEventListener('keydown', handleKeyDown);
+        return () => {
+            trigger.removeEventListener('keydown', handleKeyDown);
+        };
+    }, [lastElementRefInFlow, popperRef]);
 }
 
 export { usePickerDocumentEventClose };

package/Table/Table.js

@@ -16,6 +16,7 @@ import { useTableScroll } from './hooks/useTableScroll.js';
 import { useTableSelection } from './hooks/useTableSelection.js';
 import { useTableSorting } from './hooks/useTableSorting.js';
 import { getNumericCSSVariablePixelValue } from '../utils/get-css-variable-value.js';
+import { useIsomorphicLayoutEffect } from '../hooks/useIsomorphicLayoutEffect.js';
 import { spacingPrefix } from '@mezzanine-ui/system/spacing';
 import TableBulkActions from './components/TableBulkActions.js';
 import { useComposeRefs } from '../hooks/useComposeRefs.js';
@@ -33,27 +34,31 @@ function TableInner(props, ref) {
         }))
         : dataSource;
     /** Feature: Row Height Preset */
-    const rowHeight = useMemo(() => {
+    const rowHeightVariableName = useMemo(() => {
         switch (rowHeightPreset) {
             case 'condensed':
                 return size === 'main'
-                    ? getNumericCSSVariablePixelValue(`--${spacingPrefix}-size-container-condensed`)
-                    : getNumericCSSVariablePixelValue(`--${spacingPrefix}-size-container-reduced`);
+                    ? `--${spacingPrefix}-size-container-condensed`
+                    : `--${spacingPrefix}-size-container-reduced`;
             case 'detailed':
                 return size === 'main'
-                    ? getNumericCSSVariablePixelValue(`--${spacingPrefix}-size-container-tiny`)
-                    : getNumericCSSVariablePixelValue(`--${spacingPrefix}-size-container-tightened`);
+                    ? `--${spacingPrefix}-size-container-tiny`
+                    : `--${spacingPrefix}-size-container-tightened`;
             case 'roomy':
                 return size === 'main'
-                    ? getNumericCSSVariablePixelValue(`--${spacingPrefix}-size-container-small`)
-                    : getNumericCSSVariablePixelValue(`--${spacingPrefix}-size-container-medium`);
+                    ? `--${spacingPrefix}-size-container-small`
+                    : `--${spacingPrefix}-size-container-medium`;
             case 'base':
             default:
                 return size === 'main'
-                    ? getNumericCSSVariablePixelValue(`--${spacingPrefix}-size-container-minimized`)
-                    : getNumericCSSVariablePixelValue(`--${spacingPrefix}-size-container-minimal`);
+                    ? `--${spacingPrefix}-size-container-minimized`
+                    : `--${spacingPrefix}-size-container-minimal`;
         }
     }, [rowHeightPreset, size]);
+    const [rowHeight, setRowHeight] = useState(undefined);
+    useIsomorphicLayoutEffect(() => {
+        setRowHeight(getNumericCSSVariablePixelValue(rowHeightVariableName));
+    }, [rowHeightVariableName]);
     /** Feature: Highlight */
     const [hoveredRowIndex, setHoveredRowIndex] = useState(null);
     const [hoveredColumnIndex, setHoveredColumnIndex] = useState(null);

package/Table/TableContext.d.ts

@@ -60,7 +60,7 @@ export interface TableContextValue<T extends TableDataSource = TableDataSource>
     pinnable?: TablePinnable;
     resizable?: boolean;
     rowState?: TableRowState | ((rowData: TableDataSource) => TableRowState | undefined);
-    rowHeight: number;
+    rowHeight: number | undefined;
     scroll?: TableScroll;
     scrollContainerRef?: React.RefObject<HTMLDivElement | null>;
     selection?: TableSelectionState<T>;

package/Table/components/TableRow.js

@@ -45,7 +45,7 @@ const TableRowInner = forwardRef(function TableRow(props, ref) {
     const resolvedStyle = useMemo(() => ({
         ...style,
         ...draggableProvided === null || draggableProvided === void 0 ? void 0 : draggableProvided.draggableProps.style,
-        height: rowHeight,
+        ...(rowHeight !== undefined && { height: rowHeight }),
     }), [style, rowHeight, draggableProvided === null || draggableProvided === void 0 ? void 0 : draggableProvided.draggableProps.style]);
     const { containerWidth, getResizedColumnWidth, scrollLeft } = useTableSuperContext();
     const rowKey = useMemo(() => getRowKey(record), [record]);

package/Table/hooks/useTableVirtualization.js

@@ -16,7 +16,7 @@ function useTableVirtualization({ dataSource, enabled = true, isContainerReady =
         if (measuredHeight !== undefined) {
             return measuredHeight;
         }
-        return rowHeight;
+        return rowHeight !== null && rowHeight !== void 0 ? rowHeight : 0;
     }, [dataSource, rowHeight]);
     const getItemKey = useCallback((index) => {
         const record = dataSource[index];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mezzanine-ui/react",
-  "version": "1.0.4",
+  "version": "1.2.0",
   "description": "React components for mezzanine-ui",
   "author": "Mezzanine",
   "repository": {
@@ -32,7 +32,7 @@
     "@floating-ui/dom": "^1.7.4",
     "@floating-ui/react-dom": "^2.1.6",
     "@hello-pangea/dnd": "^18.0.1",
-    "@mezzanine-ui/core": "1.0.4",
+    "@mezzanine-ui/core": "1.1.0",
     "@mezzanine-ui/icons": "1.0.2",
     "@mezzanine-ui/system": "1.0.2",
     "@tanstack/react-virtual": "^3.13.13",
@@ -46,6 +46,7 @@
     "tslib": "^2.8.1"
   },
   "devDependencies": {
+    "@js-temporal/polyfill": "^0.5.1",
     "@types/lodash": "^4.17.20",
     "@types/moment": "^2.13.0",
     "@types/react": "^19.2.2",
@@ -56,5 +57,6 @@
     "moment": "^2.30.1",
     "react": "^19.2.0",
     "react-dom": "^19.2.0"
-  }
+  },
+  "gitHead": "f5fa136dac936a0debafff9ea5a3815ff0b5c040"
 }

package/temporal.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Temporal-specific entry point for Mezzanine UI React.
+ * Import from this path to use the JS-native Temporal API without loading
+ * any other date library (moment / dayjs / luxon).
+ *
+ * Runtime requirement: `globalThis.Temporal` must be available **on the
+ * client** before any import of `CalendarMethodsTemporal`. On runtimes that
+ * lack native support (Safari, Node 22), install `@js-temporal/polyfill` as
+ * a peer dependency and register it from a Client Component side-effect.
+ *
+ * @example Vite / CRA — register at the client entry
+ * ```tsx
+ * // main.tsx
+ * import { Temporal } from '@js-temporal/polyfill';
+ * (globalThis as { Temporal?: unknown }).Temporal = Temporal;
+ *
+ * import { CalendarConfigProviderTemporal, CalendarLocale } from '@mezzanine-ui/react/temporal';
+ * ```
+ *
+ * @example Next.js App Router — Server Component layouts cannot register
+ * the polyfill for the browser, so wrap it in a Client Component module:
+ * ```tsx
+ * // app/temporal-polyfill.tsx
+ * 'use client';
+ * import { Temporal } from '@js-temporal/polyfill';
+ * (globalThis as { Temporal?: unknown }).Temporal = Temporal;
+ * export function TemporalPolyfill() { return null; }
+ *
+ * // app/layout.tsx
+ * import { TemporalPolyfill } from './temporal-polyfill';
+ * import { CalendarConfigProviderTemporal, CalendarLocale } from '@mezzanine-ui/react/temporal';
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html><body>
+ *       <TemporalPolyfill />
+ *       <CalendarConfigProviderTemporal locale={CalendarLocale.ZH_TW}>
+ *         {children}
+ *       </CalendarConfigProviderTemporal>
+ *     </body></html>
+ *   );
+ * }
+ * ```
+ */
+export { CalendarLocale } from '@mezzanine-ui/core/calendar';
+export type { CalendarLocaleValue } from '@mezzanine-ui/core/calendar';
+export { default as CalendarConfigProviderTemporal } from './Calendar/CalendarConfigProviderTemporal';
+export type { CalendarConfigProviderTemporalProps } from './Calendar/CalendarConfigProviderTemporal';

package/temporal.js

@@ -0,0 +1,2 @@
+export { CalendarLocale } from '@mezzanine-ui/core/calendar';
+export { CalendarConfigProviderTemporal } from './Calendar/CalendarConfigProviderTemporal.js';