@mezzanine-ui/react 1.0.0-beta.3 → 1.0.0-beta.5

package/PageHeader/PageHeader.js

@@ -1,62 +1,76 @@
-import { jsx, jsxs } from 'react/jsx-runtime';
-import { forwardRef, Children, isValidElement, cloneElement } from 'react';
-import { ChevronLeftIcon } from '@mezzanine-ui/icons';
+import { jsxs } from 'react/jsx-runtime';
+import { forwardRef, isValidElement, cloneElement } from 'react';
 import { pageHeaderClasses } from '@mezzanine-ui/core/page-header';
-import Button from '../Button/Button.js';
-import Typography from '../Typography/Typography.js';
+import { flattenChildren } from '../utils/flatten-children.js';
 import Breadcrumb from '../Breadcrumb/Breadcrumb.js';
-import PageToolbar from '../PageToolbar/PageToolbar.js';
+import ContentHeader from '../ContentHeader/ContentHeader.js';
 import cx from 'clsx';
 
 const getBreadcrumbAndToolbar = (children) => {
     let breadcrumb;
-    let pageToolbar;
-    let backButtonOrLink;
-    const childrenArray = Children.toArray(children);
+    let contentHeader;
+    const childrenArray = flattenChildren(children);
     if (children) {
         childrenArray.forEach((child) => {
             if (!isValidElement(child))
                 return;
             if (child.type === Breadcrumb) {
+                if (breadcrumb) {
+                    console.warn('[Mezzanine][PageHeader] only accepts one Breadcrumb as its child.');
+                }
                 breadcrumb = child;
             }
-            else if (child.type === PageToolbar) {
-                pageToolbar = cloneElement(child, {
+            else if (child.type === ContentHeader) {
+                if (contentHeader) {
+                    console.warn('[Mezzanine][PageHeader] only accepts one ContentHeader as its child.');
+                }
+                const sizeProp = child.props.size;
+                if (sizeProp !== undefined && sizeProp !== 'main') {
+                    console.warn('[Mezzanine][PageHeader] ContentHeader size prop will be overridden to "main".');
+                }
+                contentHeader = cloneElement(child, {
                     size: 'main',
                 });
             }
-            else if (child.type === Button) {
-                backButtonOrLink = cloneElement(child, {
-                    iconType: 'icon-only',
-                    icon: ChevronLeftIcon,
-                    size: 'sub',
-                    variant: 'base-tertiary',
-                });
-            }
-            else if (child.type === 'a') {
-                backButtonOrLink = cloneElement(child, {
-                    children: (jsx(Button, { component: 'div', iconType: "icon-only", icon: ChevronLeftIcon, size: "sub", variant: "base-tertiary" })),
-                });
-            }
             else {
-                if (process.env.NODE_ENV !== 'production') {
-                    console.warn('PageHeader only accepts Breadcrumb, PageToolbar, Button or component with href prop as its children.');
-                }
+                console.warn('[Mezzanine][PageHeader] only accepts Breadcrumb or ContentHeader as its children.');
             }
         });
     }
-    return { breadcrumb, backButtonOrLink, pageToolbar };
+    if (!contentHeader) {
+        console.error('[Mezzanine][PageHeader] requires a ContentHeader as its child.');
+    }
+    return { breadcrumb, contentHeader };
 };
 /**
- * PageHeader component displays a page title with optional breadcrumb navigation,
- * description, back button, and action toolbar.
+ * PageHeader component
+ *
+ * Used to display the page header, typically containing a `<Breadcrumb />` and a `<ContentHeader />`.
+ *
+ * @example
+ * ```tsx
+ * <PageHeader>
+ *   <Breadcrumb
+ *     links={[
+ *       { id: '1', children: 'Home', href: '/' },
+ *       { id: '2', children: 'Page Header' },
+ *     ]}
+ *   />
+ *
+ *   <ContentHeader
+ *     title="Page Title"
+ *     description="This is the page description."
+ *   >
+ *     <Button variant="base-secondary">Secondary</Button>
+ *     <Button>Primary</Button>
+ *   </ContentHeader>
+ * </PageHeader>
+ * ```
  */
 const PageHeader = forwardRef(function PageHeader(props, ref) {
-    const { children, className, description, onBackClick, title, titleComponent = 'h2', ...rest } = props;
-    const { backButtonOrLink, breadcrumb, pageToolbar } = getBreadcrumbAndToolbar(children);
-    // prop onBack takes precedence over backButtonOrLink
-    const backButton = onBackClick ? (jsx(Button, { iconType: "icon-only", icon: ChevronLeftIcon, onClick: onBackClick, size: "sub", variant: "base-tertiary" })) : (backButtonOrLink);
-    return (jsxs("header", { ...rest, className: cx(pageHeaderClasses.host, className), ref: ref, children: [breadcrumb, jsxs("span", { className: pageHeaderClasses.headerContent, children: [jsxs("span", { className: pageHeaderClasses.pageTitleWithIcon, children: [backButton && jsx("div", { children: backButton }), jsxs("div", { className: pageHeaderClasses.pageTitleText, children: [jsx(Typography, { align: "left", color: "text-neutral-solid", component: titleComponent, variant: "h2", children: title }), description && (jsx(Typography, { align: "left", color: "text-neutral", component: "p", variant: "caption", children: description }))] })] }), pageToolbar] })] }));
+    const { children, className, ...rest } = props;
+    const { breadcrumb, contentHeader } = getBreadcrumbAndToolbar(children);
+    return (jsxs("header", { ...rest, className: cx(pageHeaderClasses.host, className), ref: ref, children: [breadcrumb, contentHeader] }));
 });
 
 export { PageHeader as default };

package/Popper/Popper.js

@@ -1,7 +1,7 @@
 'use client';
 import { jsx, jsxs } from 'react/jsx-runtime';
 import { forwardRef, useRef, useImperativeHandle, useEffect, useCallback } from 'react';
-import { useFloating, arrow } from '@floating-ui/react-dom';
+import { useFloating, arrow, autoUpdate } from '@floating-ui/react-dom';
 import { spacingPrefix } from '@mezzanine-ui/system/spacing';
 import { getElement } from '../utils/getElement.js';
 import { useComposeRefs } from '../hooks/useComposeRefs.js';
@@ -15,6 +15,7 @@ const Popper = forwardRef(function Popper(props, ref) {
     const anchorEl = getElement(anchor);
     const floatingReturn = useFloating({
         ...options,
+        whileElementsMounted: autoUpdate,
         middleware: [
             ...((_a = options === null || options === void 0 ? void 0 : options.middleware) !== null && _a !== void 0 ? _a : []),
             (arrow$1 === null || arrow$1 === void 0 ? void 0 : arrow$1.enabled)

package/ResultState/ResultState.d.ts

@@ -1,4 +1,5 @@
 import type { ResultStateSize, ResultStateType } from '@mezzanine-ui/core/result-state';
+import { ReactElement } from 'react';
 import type { ButtonProps } from '../Button';
 import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
 /**
@@ -26,6 +27,14 @@ export interface ResultStateProps extends NativeElementPropsWithoutKeyAndRef<'di
      * - Two buttons: Both `secondaryButton` and `primaryButton`
      */
     actions?: ResultStateActions;
+    /**
+     * Child button elements for actions. <br />
+     * Can be a single Button element or an array of one or two Button elements. <br />
+     * When using children, the first Button is treated as secondary and the second as primary. <br />
+     * If only one Button is provided, it is treated as secondary. <br />
+     * If actions provided, children will be ignored. <br />
+     */
+    children?: ReactElement<ButtonProps> | [ReactElement<ButtonProps>] | [ReactElement<ButtonProps>, ReactElement<ButtonProps>];
     /**
      * Optional description text displayed below the title.
      * Provides additional context or details about the result state.

package/ResultState/ResultState.js

@@ -1,9 +1,10 @@
-import { jsx, jsxs } from 'react/jsx-runtime';
+import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
 import { resultStateClasses } from '@mezzanine-ui/core/result-state';
-import { forwardRef, useMemo } from 'react';
+import { forwardRef, useMemo, isValidElement, cloneElement } from 'react';
 import { DangerousFilledIcon, ErrorFilledIcon, WarningFilledIcon, QuestionFilledIcon, CheckedFilledIcon, InfoFilledIcon } from '@mezzanine-ui/icons';
 import Button from '../Button/Button.js';
 import ButtonGroup from '../Button/ButtonGroup.js';
+import { flattenChildren } from '../utils/flatten-children.js';
 import Icon from '../Icon/Icon.js';
 import cx from 'clsx';
 
@@ -15,10 +16,41 @@ const iconMap = {
     error: ErrorFilledIcon,
     failure: DangerousFilledIcon,
 };
+const renderButtonOrElement = (button, size, variant) => {
+    if (!button)
+        return null;
+    if (isValidElement(button)) {
+        return cloneElement(button, { size, variant });
+    }
+    return jsx(Button, { ...button, size: size, variant: variant });
+};
 const ResultState = forwardRef(function ResultState(props, ref) {
-    const { actions, className, description, size = 'main', title, type = 'information', ...rest } = props;
+    const { actions, className, children, description, size = 'main', title, type = 'information', ...rest } = props;
     const icon = useMemo(() => iconMap[type], [type]);
-    return (jsx("div", { ...rest, ref: ref, className: cx(resultStateClasses.host, resultStateClasses.type(type), resultStateClasses.size(size), className), children: jsxs("div", { className: resultStateClasses.container, children: [jsx(Icon, { className: resultStateClasses.icon, icon: icon }), jsx("h3", { className: resultStateClasses.title, children: title }), description && jsx("p", { className: resultStateClasses.description, children: description }), ((actions === null || actions === void 0 ? void 0 : actions.secondaryButton) || (actions === null || actions === void 0 ? void 0 : actions.primaryButton)) && (jsxs(ButtonGroup, { className: resultStateClasses.actions, children: [(actions === null || actions === void 0 ? void 0 : actions.secondaryButton) && (jsx(Button, { size: size, variant: "base-secondary", ...actions.secondaryButton })), (actions === null || actions === void 0 ? void 0 : actions.primaryButton) && (jsx(Button, { size: size, variant: "base-primary", ...actions.primaryButton }))] }))] }) }));
+    const flatChildren = flattenChildren(children);
+    const fragmentButtons = actions &&
+        ('secondaryButton' in actions ? (jsxs(Fragment, { children: [renderButtonOrElement(actions.secondaryButton, size, 'base-secondary'), renderButtonOrElement(actions.primaryButton, size, 'base-primary')] })) : (renderButtonOrElement(actions, size, 'base-secondary')));
+    const renderChildren = !fragmentButtons &&
+        flatChildren.length > 0 &&
+        flatChildren.map((child, index) => {
+            if (!isValidElement(child)) {
+                return null;
+            }
+            else if (child.type === Button) {
+                switch (index) {
+                    case 0:
+                        return renderButtonOrElement(child, size, 'base-secondary');
+                    case 1:
+                        return renderButtonOrElement(child, size, 'base-primary');
+                    default:
+                        console.warn('Only up to two Button components are allowed as children of ResultState.');
+                        return null;
+                }
+            }
+            console.warn('Only Button components are allowed as children of ResultState.');
+            return null;
+        });
+    return (jsx("div", { ...rest, ref: ref, className: cx(resultStateClasses.host, resultStateClasses.type(type), resultStateClasses.size(size), className), children: jsxs("div", { className: resultStateClasses.container, children: [jsx(Icon, { className: resultStateClasses.icon, icon: icon }), jsx("h3", { className: resultStateClasses.title, children: title }), description && jsx("p", { className: resultStateClasses.description, children: description }), actions || children ? (jsx(ButtonGroup, { className: resultStateClasses.actions, children: fragmentButtons || renderChildren })) : null] }) }));
 });
 
 export { ResultState as default };

package/Scrollbar/Scrollbar.d.ts

@@ -0,0 +1,9 @@
+import 'overlayscrollbars/overlayscrollbars.css';
+import { OverlayScrollbarsComponentRef } from 'overlayscrollbars-react';
+import type { ScrollbarProps } from './typings';
+/**
+ * The react component for `mezzanine` scrollbar.
+ * A customizable scrollbar container that provides consistent styling across all browsers
+ */
+declare const Scrollbar: import("react").ForwardRefExoticComponent<ScrollbarProps & import("react").RefAttributes<OverlayScrollbarsComponentRef<"div">>>;
+export default Scrollbar;

package/Scrollbar/Scrollbar.js

@@ -0,0 +1,79 @@
+import { jsx } from 'react/jsx-runtime';
+import 'overlayscrollbars/overlayscrollbars.css';
+import { forwardRef, useEffect, useMemo, useCallback } from 'react';
+import { OverlayScrollbars, ClickScrollPlugin } from 'overlayscrollbars';
+import { OverlayScrollbarsComponent } from 'overlayscrollbars-react';
+import { scrollbarClasses } from '@mezzanine-ui/core/scrollbar';
+import cx from 'clsx';
+
+/**
+ * The react component for `mezzanine` scrollbar.
+ * A customizable scrollbar container that provides consistent styling across all browsers
+ */
+const Scrollbar = forwardRef(function Scrollbar(props, ref) {
+    const { children, className, defer = true, disabled = false, events, maxHeight, maxWidth, onViewportReady, options, style, ...rest } = props;
+    // Register ClickScrollPlugin once (required for clickScroll option to work)
+    useEffect(() => {
+        OverlayScrollbars.plugin(ClickScrollPlugin);
+    }, []);
+    const mergedOptions = useMemo(() => ({
+        ...options,
+        overflow: {
+            x: 'scroll',
+            y: 'scroll',
+        },
+        scrollbars: {
+            autoHide: 'scroll',
+            autoHideDelay: 600,
+            clickScroll: true,
+            ...options === null || options === void 0 ? void 0 : options.scrollbars,
+        },
+    }), [options]);
+    const containerStyle = useMemo(() => ({
+        ...style,
+        maxHeight,
+        maxWidth,
+    }), [maxHeight, maxWidth, style]);
+    // Merge events with onViewportReady callback
+    const mergedEvents = useMemo(() => {
+        if (!onViewportReady && !events)
+            return undefined;
+        return {
+            ...events,
+            initialized: (instance) => {
+                const { viewport } = instance.elements();
+                onViewportReady === null || onViewportReady === void 0 ? void 0 : onViewportReady(viewport, instance);
+                if (events && typeof events !== 'boolean' && events.initialized) {
+                    const initializedHandler = events.initialized;
+                    if (Array.isArray(initializedHandler)) {
+                        initializedHandler.forEach((handler) => handler(instance));
+                    }
+                    else {
+                        initializedHandler(instance);
+                    }
+                }
+            },
+        };
+    }, [events, onViewportReady]);
+    // Callback ref for disabled mode - triggers onViewportReady with the div element
+    const disabledRef = useCallback((element) => {
+        // Forward to user ref if provided
+        if (typeof ref === 'function') {
+            ref(element);
+        }
+        else if (ref) {
+            ref.current = element;
+        }
+        // Call onViewportReady with the div element (no OverlayScrollbars instance)
+        if (element && onViewportReady) {
+            onViewportReady(element);
+        }
+    }, [onViewportReady, ref]);
+    // When disabled, render a plain div instead of OverlayScrollbarsComponent
+    if (disabled) {
+        return (jsx("div", { ...rest, ref: disabledRef, className: className, style: containerStyle, children: children }));
+    }
+    return (jsx(OverlayScrollbarsComponent, { ...rest, ref: ref, className: cx(scrollbarClasses.host, className), defer: defer, element: "div", events: mergedEvents, options: mergedOptions, style: containerStyle, children: children }));
+});
+
+export { Scrollbar as default };

package/Scrollbar/index.d.ts

@@ -0,0 +1,2 @@
+export type { ScrollbarProps } from './typings';
+export { default } from './Scrollbar';

package/Scrollbar/index.js

@@ -0,0 +1 @@
+export { default } from './Scrollbar.js';

package/Scrollbar/typings.d.ts

@@ -0,0 +1,47 @@
+import type { OverlayScrollbars, PartialOptions } from 'overlayscrollbars';
+import type { OverlayScrollbarsComponentProps } from 'overlayscrollbars-react';
+import type { CSSProperties, ReactNode } from 'react';
+import type { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
+export interface ScrollbarProps extends Omit<NativeElementPropsWithoutKeyAndRef<'div'>, 'children'> {
+    /**
+     * The content to be rendered inside the scrollable container.
+     */
+    children?: ReactNode;
+    /**
+     * Whether to defer the initialization of OverlayScrollbars.
+     * This can improve initial render performance.
+     * @default true
+     */
+    defer?: boolean | object;
+    /**
+     * When true, disables the custom scrollbar and renders as a plain div.
+     * Useful for nested contexts where custom scrollbar is not needed.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * The maximum height of the scrollable container.
+     * Can be a CSS value string (e.g., '300px', '50vh') or a number (treated as pixels).
+     */
+    maxHeight?: CSSProperties['maxHeight'];
+    /**
+     * The maximum width of the scrollable container.
+     * Can be a CSS value string (e.g., '500px', '100%') or a number (treated as pixels).
+     */
+    maxWidth?: CSSProperties['maxWidth'];
+    /**
+     * Additional options to pass to OverlayScrollbars.
+     * @see https://kingsora.github.io/OverlayScrollbars/#!documentation/options
+     */
+    options?: PartialOptions;
+    /**
+     * Event handlers for OverlayScrollbars events.
+     * @see https://kingsora.github.io/OverlayScrollbars/#!documentation/events
+     */
+    events?: OverlayScrollbarsComponentProps['events'];
+    /**
+     * Callback fired when the scrollbar is initialized.
+     * Provides access to the viewport element for external integrations (e.g., virtualization, DnD).
+     */
+    onViewportReady?: (viewport: HTMLDivElement, instance?: OverlayScrollbars) => void;
+}

package/Select/Select.d.ts

@@ -1,33 +1,52 @@
+import { DropdownOption, DropdownType } from '@mezzanine-ui/core/dropdown/dropdown';
 import { SelectInputSize } from '@mezzanine-ui/core/select';
+import React, { ReactElement } from 'react';
 import { FormElementFocusHandlers } from '../Form';
-import { MenuProps } from '../Menu';
-import { PopperProps } from '../Popper';
-import { SelectValue } from './typings';
-import { PickRenameMulti } from '../utils/general';
-import { SelectTriggerProps, SelectTriggerInputProps } from './SelectTrigger';
-export interface SelectBaseProps extends Omit<SelectTriggerProps, 'active' | 'inputProps' | 'mode' | 'onBlur' | 'onChange' | 'onClick' | 'onFocus' | 'onKeyDown' | 'onScroll' | 'readOnly' | 'renderValue' | 'value'>, FormElementFocusHandlers, PickRenameMulti<Pick<MenuProps, 'itemsInView' | 'maxHeight' | 'role' | 'size'>, {
-    maxHeight: 'menuMaxHeight';
-    role: 'menuRole';
-    size: 'menuSize';
-}>, PickRenameMulti<Pick<PopperProps, 'options' | 'disablePortal'>, {
-    options: 'popperOptions';
-    disablePortal: 'disablePortal';
-}>, Pick<MenuProps, 'children'> {
+import { SelectTriggerInputProps, SelectTriggerProps, SelectValue } from './typings';
+export interface SelectBaseProps extends Omit<SelectTriggerProps, 'active' | 'inputProps' | 'mode' | 'onBlur' | 'onChange' | 'onClick' | 'onFocus' | 'onKeyDown' | 'onScroll' | 'type' | 'renderValue' | 'value'>, FormElementFocusHandlers {
+    /**
+     * The children of select (Option components).
+     * If `options` is provided, this will be ignored.
+     */
+    children?: ReactElement | ReactElement[];
+    /**
+     * Direct options array for dropdown (supports tree structure).
+     * If provided, `children` will be ignored and `type` will be automatically set.
+     */
+    options?: DropdownOption[];
+    /**
+     * The type of dropdown.
+     * @default 'default'
+     */
+    type?: DropdownType;
     /**
      * The other native props for input element.
      */
     inputProps?: Omit<SelectTriggerInputProps, 'onBlur' | 'onChange' | 'onFocus' | 'placeholder' | 'role' | 'value' | `aria-${'controls' | 'expanded' | 'owns'}`>;
+    /**
+     * Whether to disable portal.
+     */
+    disablePortal?: boolean;
+    /**
+     * The max height of the dropdown list.
+     */
+    menuMaxHeight?: number | string;
     /**
      * Popup menu scroll listener
      */
-    onMenuScroll?: (computed: {
+    onScroll?: (computed: {
         scrollTop: number;
         maxScrollTop: number;
-    }, target: HTMLUListElement) => void;
+    }, target: HTMLDivElement) => void;
     /**
      * select input placeholder
      */
     placeholder?: string;
+    /**
+     * Whether the input is readonly.
+     * @default false
+     */
+    readOnly?: boolean;
     /**
      * To customize rendering select input value
      */
@@ -54,7 +73,7 @@ export type SelectMultipleProps = SelectBaseProps & {
     /**
      * The change event handler of input element.
      */
-    onChange?(newOptions: SelectValue[]): any;
+    onChange?(newOptions: SelectValue[]): void;
     /**
      * To customize rendering select input value
      */
@@ -77,7 +96,7 @@ export type SelectSingleProps = SelectBaseProps & {
     /**
      * The change event handler of input element.
      */
-    onChange?(newOptions: SelectValue): any;
+    onChange?(newOptions: SelectValue | null): void;
     /**
      * To customize rendering select input value
      */
@@ -89,5 +108,5 @@ export type SelectSingleProps = SelectBaseProps & {
     value?: SelectValue | null;
 };
 export type SelectProps = SelectMultipleProps | SelectSingleProps;
-declare const Select: import("react").ForwardRefExoticComponent<(Omit<SelectMultipleProps, "ref"> | Omit<SelectSingleProps, "ref">) & import("react").RefAttributes<HTMLDivElement>>;
+declare const Select: React.ForwardRefExoticComponent<SelectProps & React.RefAttributes<HTMLDivElement>>;
 export default Select;