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

package/Anchor/Anchor.d.ts

@@ -1,30 +1,63 @@
-import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
-export interface AnchorProps extends Omit<NativeElementPropsWithoutKeyAndRef<'div'>, 'onClick'> {
-    /** The current active anchor ID */
-    activeAnchorId?: string;
-    /** Whether apply ellipsis or not
-     * @default false
+import { ReactElement } from 'react';
+import { AnchorItemData } from './AnchorItem';
+export interface AnchorPropsWithAnchors {
+    /**
+     * ```tsx
+     * interface AnchorItemData {
+     *   autoScrollTo?: boolean;
+     *   children?: AnchorItemData[];
+     *   disabled?: boolean;
+     *   href: string;
+     *   id: string;
+     *   name: string;
+     *   onClick?: VoidFunction;
+     *   title?: string;
+     * }
+     * ```
+     */
+    anchors: AnchorItemData[];
+    children?: never;
+}
+export interface AnchorPropsWithChildren {
+    anchors?: never;
+    /**
+     * Whether to enable smooth scrolling to the target element when clicked.
+     */
+    autoScrollTo?: boolean;
+    /**
+     * Use nested `<Anchor>` components to create hierarchical navigation. <br />
+     * Only accepts `<Anchor>` components and text content as children. <br />
+     * ```tsx
+     * <AnchorGroup>
+     *   <Anchor href="#acr1">ACR 1</Anchor>
+     *   <Anchor href="#acr2">
+     *     anchor 2
+     *     <Anchor href="#acr2-1">ACR 2-1</Anchor>
+     *     <Anchor href="#acr2-2">ACR 2-2</Anchor>
+     *   </Anchor>
+     * </AnchorGroup>
+     * ```
      */
-    ellipsis?: boolean;
+    children: string | ReactElement<AnchorPropsWithChildren, typeof Anchor> | Array<string | ReactElement<AnchorPropsWithChildren, typeof Anchor>>;
     /**
-     * Anchor list.
+     * Whether the anchor is disabled.<br>
+     * If parent anchor is disabled, all its children will be disabled too. <br />
      */
-    list: {
-        id: string;
-        name: string;
-    }[];
+    disabled?: boolean;
     /**
-     * The maximum width for anchor container. This might be useful when you need to set `ellipsis: true`.
+     * Required when used as child component.
      */
-    maxWidth?: number;
+    href?: string;
     /**
      * Trigger when user click on any anchor.
      */
-    onClick?: (nextAnchorId: string) => void;
+    onClick?: VoidFunction;
+    title?: string;
 }
+export type AnchorProps = AnchorPropsWithAnchors | AnchorPropsWithChildren;
 /**
- * The react component for `mezzanine` anchor.
- * This component should always be full width of its parent.
+ * The `mezzanine` Anchor component provides navigation menu for page sections with automatic hash tracking.
+ * Nested structure supports up to 3 levels; deeper levels will be ignored.
  */
-declare const Anchor: import("react").ForwardRefExoticComponent<AnchorProps & import("react").RefAttributes<HTMLDivElement>>;
+declare function Anchor(props: AnchorProps): import("react/jsx-runtime").JSX.Element;
 export default Anchor;

package/Anchor/Anchor.js

@@ -1,20 +1,20 @@
-import { jsxs, jsx } from 'react/jsx-runtime';
-import { forwardRef } from 'react';
-import { anchorClasses } from '@mezzanine-ui/core/anchor';
-import Typography from '../Typography/Typography.js';
-import cx from 'clsx';
+'use client';
+import { jsx } from 'react/jsx-runtime';
+import { Fragment } from 'react';
+import AnchorItem from './AnchorItem.js';
+import { parseChildren } from './utils.js';
 
 /**
- * The react component for `mezzanine` anchor.
- * This component should always be full width of its parent.
+ * The `mezzanine` Anchor component provides navigation menu for page sections with automatic hash tracking.
+ * Nested structure supports up to 3 levels; deeper levels will be ignored.
  */
-const Anchor = forwardRef(function Anchor(props, ref) {
-    const { activeAnchorId, className, ellipsis = false, list, maxWidth, onClick, style, ...rest } = props;
-    const resolvedStyle = {
-        ...(style || {}),
-        ...(maxWidth ? { maxWidth: `${maxWidth}px` } : {}),
-    };
-    return (jsxs("div", { ref: ref, className: cx(anchorClasses.host, className), style: resolvedStyle, ...rest, children: [jsx("div", { className: anchorClasses.bar }), list.map((anchor) => (jsx("button", { type: "button", onClick: () => onClick === null || onClick === void 0 ? void 0 : onClick(anchor.id), className: cx(anchorClasses.anchor, activeAnchorId === anchor.id && anchorClasses.anchorActive), children: jsx(Typography, { variant: "input3", color: "inherit", ellipsis: ellipsis, children: anchor.name }) }, anchor.id)))] }));
-});
+function Anchor(props) {
+    const anchorItems = 'anchors' in props && props.anchors
+        ? props.anchors
+        : 'children' in props && props.children
+            ? parseChildren(props.children, Anchor)
+            : [];
+    return (jsx(Fragment, { children: anchorItems.map((anchorItem) => (jsx(AnchorItem, { autoScrollTo: anchorItem.autoScrollTo, disabled: anchorItem.disabled, href: anchorItem.href, id: anchorItem.id, name: anchorItem.name, onClick: anchorItem.onClick, subAnchors: anchorItem.children, title: anchorItem.title }, anchorItem.id))) }));
+}
 
 export { Anchor as default };

package/Anchor/AnchorGroup.d.ts

@@ -0,0 +1,34 @@
+import { ReactElement } from 'react';
+import Anchor from './Anchor';
+import type { AnchorPropsWithAnchors, AnchorPropsWithChildren } from './Anchor';
+type AnchorElement = ReactElement<AnchorPropsWithChildren, typeof Anchor>;
+type AnchorChildren = AnchorElement | AnchorElement[];
+export type AnchorGroupPropsWithAnchors = AnchorPropsWithAnchors;
+export interface AnchorGroupPropsWithChildren {
+    anchors?: never;
+    children: AnchorChildren;
+}
+type AnchorGroupBaseProps = AnchorGroupPropsWithAnchors | AnchorGroupPropsWithChildren;
+export type AnchorGroupProps = AnchorGroupBaseProps & {
+    className?: string;
+};
+/**
+ * The `mezzanine` AnchorGroup component renders a group of anchor links,
+ * configured via an `anchors` prop or parsed from `Anchor` child components.
+ *
+ * ```tsx
+ * <AnchorGroup>
+ *   <Anchor href="#section1">Section 1</Anchor>
+ *   <Anchor href="#section2">Section 2</Anchor>
+ * </AnchorGroup>
+ * ```
+ *
+ * ```tsx
+ * <AnchorGroup anchors={[
+ *   { id: 'section1', name: 'Section 1', href: '#section1' },
+ *   { id: 'section2', name: 'Section 2', href: '#section2' }
+ * ]} />
+ * ```
+ */
+declare const AnchorGroup: import("react").ForwardRefExoticComponent<AnchorGroupProps & import("react").RefAttributes<HTMLDivElement>>;
+export default AnchorGroup;

package/Anchor/AnchorGroup.js

@@ -0,0 +1,37 @@
+'use client';
+import { jsx } from 'react/jsx-runtime';
+import { forwardRef } from 'react';
+import { anchorClasses } from '@mezzanine-ui/core/anchor';
+import Anchor from './Anchor.js';
+import { parseChildren } from './utils.js';
+import cx from 'clsx';
+
+/**
+ * The `mezzanine` AnchorGroup component renders a group of anchor links,
+ * configured via an `anchors` prop or parsed from `Anchor` child components.
+ *
+ * ```tsx
+ * <AnchorGroup>
+ *   <Anchor href="#section1">Section 1</Anchor>
+ *   <Anchor href="#section2">Section 2</Anchor>
+ * </AnchorGroup>
+ * ```
+ *
+ * ```tsx
+ * <AnchorGroup anchors={[
+ *   { id: 'section1', name: 'Section 1', href: '#section1' },
+ *   { id: 'section2', name: 'Section 2', href: '#section2' }
+ * ]} />
+ * ```
+ */
+const AnchorGroup = forwardRef(function AnchorGroup(props, ref) {
+    const { className } = props;
+    const anchorItems = 'anchors' in props && props.anchors
+        ? props.anchors
+        : 'children' in props && props.children
+            ? parseChildren(props.children, Anchor)
+            : [];
+    return (jsx("div", { ref: ref, className: cx(anchorClasses.host, className), children: jsx(Anchor, { anchors: anchorItems }) }));
+});
+
+export { AnchorGroup as default };

package/Anchor/AnchorItem.d.ts

@@ -0,0 +1,30 @@
+export interface AnchorItemData {
+    autoScrollTo?: boolean;
+    children?: AnchorItemData[];
+    disabled?: boolean;
+    href: string;
+    id: string;
+    name: string;
+    onClick?: VoidFunction;
+    title?: string;
+}
+export interface AnchorItemProps {
+    autoScrollTo?: boolean;
+    className?: string;
+    disabled?: boolean;
+    href: string;
+    id: string;
+    level?: number;
+    name: string;
+    onClick?: VoidFunction;
+    parentAutoScrollTo?: boolean;
+    parentDisabled?: boolean;
+    subAnchors?: AnchorItemData[];
+    title?: string;
+}
+/**
+ * Individual anchor link with hash tracking and smooth scrolling.
+ * Tracks active state from URL hash and inherits disabled state from parent.
+ */
+declare function AnchorItem({ autoScrollTo, className, disabled, href, id: _id, level, name, onClick, parentAutoScrollTo, parentDisabled, subAnchors, title, }: AnchorItemProps): import("react/jsx-runtime").JSX.Element;
+export default AnchorItem;

package/Anchor/AnchorItem.js

@@ -0,0 +1,65 @@
+'use client';
+import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
+import { useState, useEffect } from 'react';
+import { anchorClasses } from '@mezzanine-ui/core/anchor';
+import Typography from '../Typography/Typography.js';
+import cx from 'clsx';
+
+const MAX_CHILDREN_PER_LEVEL = 3;
+/**
+ * Custom hook to track window.location.hash changes
+ */
+function useHash() {
+    const [hash, setHash] = useState(() => typeof window !== 'undefined' ? window.location.hash : '');
+    useEffect(() => {
+        const handleHashChange = () => {
+            setHash(window.location.hash);
+        };
+        window.addEventListener('hashchange', handleHashChange);
+        return () => {
+            window.removeEventListener('hashchange', handleHashChange);
+        };
+    }, []);
+    return hash;
+}
+/**
+ * Individual anchor link with hash tracking and smooth scrolling.
+ * Tracks active state from URL hash and inherits disabled state from parent.
+ */
+function AnchorItem({ autoScrollTo, className, disabled, href, id: _id, level = 1, name, onClick, parentAutoScrollTo = false, parentDisabled = false, subAnchors, title, }) {
+    const renderableChildren = subAnchors && subAnchors.length > 0 && level < MAX_CHILDREN_PER_LEVEL
+        ? subAnchors.slice(0, MAX_CHILDREN_PER_LEVEL)
+        : undefined;
+    const currentHash = useHash();
+    const hashIndex = href.indexOf('#');
+    const itemHash = hashIndex !== -1 ? href.slice(hashIndex) : '';
+    const isActive = itemHash && currentHash === itemHash;
+    const isAutoScrollTo = parentAutoScrollTo || autoScrollTo;
+    const isDisabled = parentDisabled || disabled;
+    const handleClick = (event) => {
+        if (isDisabled) {
+            event.preventDefault();
+            return;
+        }
+        // If href contains a hash, handle navigation manually to ensure hashchange event fires
+        if (itemHash && typeof window !== 'undefined') {
+            event.preventDefault();
+            // Update the hash in the URL only if it's different
+            if (window.location.hash !== itemHash) {
+                window.history.pushState(null, '', itemHash);
+                window.dispatchEvent(new HashChangeEvent('hashchange'));
+            }
+            // Scroll to the target element if it exists and autoScrollTo is enabled
+            if (isAutoScrollTo) {
+                const targetElement = document.querySelector(itemHash);
+                if (targetElement) {
+                    targetElement.scrollIntoView({ behavior: 'smooth', block: 'start' });
+                }
+            }
+        }
+        onClick === null || onClick === void 0 ? void 0 : onClick();
+    };
+    return (jsxs(Fragment, { children: [jsx("a", { "aria-disabled": isDisabled, className: cx(anchorClasses.anchorItem, isActive && anchorClasses.anchorItemActive, isDisabled && anchorClasses.anchorItemDisabled, className), href: href, onClick: handleClick, tabIndex: isDisabled ? -1 : undefined, title: title, children: jsx(Typography, { color: "inherit", variant: "label-primary", children: name }) }), renderableChildren && (jsx("div", { className: anchorClasses.nested, children: renderableChildren.map((child) => (jsx(AnchorItem, { autoScrollTo: child.autoScrollTo, className: cx(level === 1 && anchorClasses.nestedLevel1, level === 2 && anchorClasses.nestedLevel2), disabled: child.disabled, href: child.href, id: child.id, level: level + 1, name: child.name, onClick: child.onClick, parentAutoScrollTo: isAutoScrollTo, parentDisabled: isDisabled, subAnchors: child.children, title: child.title }, child.id))) }))] }));
+}
+
+export { AnchorItem as default };

package/Anchor/index.d.ts

@@ -1,2 +1,4 @@
+export type { AnchorGroupProps } from './AnchorGroup';
+export { default as AnchorGroup } from './AnchorGroup';
 export type { AnchorProps } from './Anchor';
 export { default } from './Anchor';

package/Anchor/index.js

@@ -1 +1,2 @@
+export { default as AnchorGroup } from './AnchorGroup.js';
 export { default } from './Anchor.js';

package/Anchor/utils.d.ts

@@ -0,0 +1,13 @@
+import { type ReactNode } from 'react';
+import Anchor from './Anchor';
+import type { AnchorItemData } from './AnchorItem';
+type AnchorComponentType = typeof Anchor;
+/**
+ * Extract text content from ReactNode, excluding Anchor components
+ */
+export declare function extractTextContent(node: ReactNode, AnchorComponent: AnchorComponentType): string;
+/**
+ * Parse children to extract anchor data
+ */
+export declare function parseChildren(children: ReactNode, AnchorComponent: AnchorComponentType): AnchorItemData[];
+export {};

package/Anchor/utils.js

@@ -0,0 +1,95 @@
+import { Children, isValidElement } from 'react';
+
+/**
+ * Extract text content from ReactNode, excluding Anchor components
+ */
+function extractTextContent(node, AnchorComponent) {
+    if (typeof node === 'string') {
+        return node;
+    }
+    if (Array.isArray(node)) {
+        return node.map((n) => extractTextContent(n, AnchorComponent)).join('');
+    }
+    if (isValidElement(node)) {
+        if (node.type === AnchorComponent) {
+            return '';
+        }
+        return extractTextContent(node.props.children, AnchorComponent);
+    }
+    return '';
+}
+/**
+ * Parse children to extract anchor data
+ */
+function parseChildren(children, AnchorComponent) {
+    const items = [];
+    Children.forEach(children, (child) => {
+        if (typeof child === 'string') {
+            return;
+        }
+        if (isValidElement(child) && child.type !== AnchorComponent) {
+            const displayName = typeof child.type === 'string'
+                ? child.type
+                : child.type.displayName
+                    || child.type.name
+                    || 'Unknown';
+            console.warn(`[Anchor] Invalid child type: <${displayName}>. Only <Anchor> components or strings are allowed as children. This element will be ignored.`);
+            return;
+        }
+        if (isValidElement(child) && child.type === AnchorComponent) {
+            const { children: nestedChildren, ...childProps } = child.props;
+            let href;
+            let id;
+            let name;
+            let nestedItems = [];
+            if ('anchors' in childProps && childProps.anchors) {
+                items.push(...childProps.anchors);
+                return;
+            }
+            if ('href' in childProps) {
+                href = childProps.href;
+            }
+            if (!href) {
+                return;
+            }
+            if (typeof nestedChildren === 'string') {
+                id = nestedChildren;
+                name = nestedChildren;
+            }
+            else if (isValidElement(nestedChildren)) {
+                nestedItems = parseChildren(nestedChildren, AnchorComponent);
+                if (nestedItems.length > 0) {
+                    id = nestedItems[0].id;
+                    name = nestedItems[0].name;
+                }
+                else {
+                    const textContent = extractTextContent(nestedChildren, AnchorComponent);
+                    id = textContent;
+                    name = textContent;
+                }
+            }
+            else {
+                const parsedNested = parseChildren(nestedChildren, AnchorComponent);
+                if (parsedNested.length > 0) {
+                    nestedItems = parsedNested;
+                }
+                const textContent = extractTextContent(nestedChildren, AnchorComponent);
+                id = textContent;
+                name = textContent;
+            }
+            items.push({
+                autoScrollTo: 'autoScrollTo' in childProps ? childProps.autoScrollTo : undefined,
+                children: nestedItems.length > 0 ? nestedItems : undefined,
+                disabled: 'disabled' in childProps ? childProps.disabled : undefined,
+                href,
+                id,
+                name,
+                onClick: 'onClick' in childProps ? childProps.onClick : undefined,
+                title: 'title' in childProps ? childProps.title : undefined,
+            });
+        }
+    });
+    return items;
+}
+
+export { extractTextContent, parseChildren };

package/AutoComplete/AutoComplete.d.ts

@@ -0,0 +1,194 @@
+import { Dispatch, RefObject, SetStateAction } from 'react';
+import { AutoCompleteSelector } from '@mezzanine-ui/core/autocomplete';
+import { DropdownInputPosition } from '@mezzanine-ui/core/dropdown/dropdown';
+import { PopperProps } from '../Popper';
+import type { SelectTriggerInputProps, SelectTriggerProps } from '../Select/typings';
+import { SelectValue } from '../Select/typings';
+import { PickRenameMulti } from '../utils/general';
+export interface AutoCompleteBaseProps extends Omit<SelectTriggerProps, 'active' | 'clearable' | 'forceHideSuffixActionIcon' | 'mode' | 'onClick' | 'onKeyDown' | 'onChange' | 'renderValue' | 'inputProps' | 'suffixActionIcon' | 'value'>, PickRenameMulti<Pick<PopperProps, 'options'>, {
+    options: 'popperOptions';
+}> {
+    /**
+     * Set to true when options can be added dynamically
+     * @default false
+     */
+    addable?: boolean;
+    /**
+     * Whether the data is fetched asynchronously.
+     * If true, input change will trigger loading until onSearch promise resolves.
+     * @default false
+     */
+    asyncData?: boolean;
+    /**
+     * Characters that can be used to separate multiple items when creating.
+     * When these characters are entered, they will trigger item creation.
+     * @default [',', '+', '\n']
+     */
+    createSeparators?: string[];
+    /**
+     * Should the filter rules be disabled (If you need to control options filter by yourself)
+     * @default false
+     */
+    disabledOptionsFilter?: boolean;
+    /**
+     * The text of the dropdown empty status.
+     */
+    emptyText?: string;
+    /**
+     * The id attribute of the input element.
+     *
+     * @important When using with react-hook-form or native forms, this prop is recommended.
+     */
+    id?: string;
+    /**
+     * The position of the input.
+     * @default 'outside'
+     */
+    inputPosition?: DropdownInputPosition;
+    /**
+     * The other native props for input element.
+     */
+    inputProps?: Omit<SelectTriggerInputProps, 'onChange' | 'placeholder' | 'role' | 'value' | `aria-${'controls' | 'expanded' | 'owns'}`>;
+    /**
+     * Whether the dropdown is in loading state.
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * The text of the dropdown loading status.
+     */
+    loadingText?: string;
+    /**
+     * The max height of the dropdown list.
+     */
+    menuMaxHeight?: number | string;
+    /**
+     * The name attribute of the input element.
+     *
+     * @important When using with react-hook-form or native forms, this prop is recommended.
+     *
+     * @example With react-hook-form
+     * ```tsx
+     * const { register } = useForm();
+     * <AutoComplete name="autocomplete" {...register('autocomplete')} />
+     * ```
+     */
+    name?: string;
+    /**
+     * insert callback whenever insert icon is clicked
+     * receives the text to insert and current options, returns the updated options array
+     * should remove previously created but unselected options
+     * The returned options will be used to update the component's options prop
+     */
+    onInsert?(text: string, currentOptions: SelectValue[]): SelectValue[];
+    /**
+     * The search event handler
+     * Can return a Promise for async data loading
+     */
+    onSearch?(input: string): void | Promise<void>;
+    /**
+     * Callback fired when the dropdown visibility changes.
+     */
+    onVisibilityChange?: (open: boolean) => void;
+    /**
+     * Whether the dropdown is open (controlled).
+     */
+    open?: boolean;
+    /**
+     * The options that mapped autocomplete options
+     */
+    options: SelectValue[];
+    /**
+     * select input placeholder
+     */
+    placeholder?: string;
+    /**
+     * Whether the selection is required.
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * The debounce time of the search event handler.
+     * @default 300
+     */
+    searchDebounceTime?: number;
+    /**
+     * Imperative handle to control search text externally (e.g. reset or sync).
+     */
+    searchTextControlRef?: RefObject<{
+        setSearchText: Dispatch<SetStateAction<string>>;
+    } | undefined>;
+    /**
+     * Whether to trim whitespace from created items.
+     * @default true
+     */
+    trimOnCreate?: boolean;
+    /**
+     * Custom text for the create action button.
+     * @default '建立 "{text}"'
+     */
+    createActionText?: (text: string) => string;
+    /**
+     * Default template for the create action button text.
+     * Use this to customize the default text format when createActionText is not provided.
+     * The template should contain {text} placeholder which will be replaced with the actual text.
+     * @default '建立 "{text}"'
+     */
+    createActionTextTemplate?: string;
+}
+export type AutoCompleteMultipleProps = AutoCompleteBaseProps & {
+    /**
+     * The default selection
+     */
+    defaultValue?: SelectValue[];
+    /**
+     * Controls the layout of trigger.
+     */
+    mode: 'multiple';
+    /**
+     * The change event handler of input element.
+     */
+    onChange?(newOptions: SelectValue[]): void;
+    /**
+     * The selector of input.
+     * @default 'input'
+     */
+    selector?: AutoCompleteSelector;
+    /**
+     * The value of selection.
+     * @default undefined
+     */
+    value?: SelectValue[];
+};
+export type AutoCompleteSingleProps = AutoCompleteBaseProps & {
+    /**
+     * The default selection
+     */
+    defaultValue?: SelectValue;
+    /**
+     * Controls the layout of trigger.
+     */
+    mode?: 'single';
+    /**
+     * The change event handler of input element.
+     */
+    onChange?(newOptions: SelectValue): void;
+    /**
+     * The selector of input.
+     * @default 'input'
+     */
+    selector?: AutoCompleteSelector;
+    /**
+     * The value of selection.
+     * @default undefined
+     */
+    value?: SelectValue | null;
+};
+export type AutoCompleteProps = AutoCompleteMultipleProps | AutoCompleteSingleProps;
+/**
+ * The AutoComplete component for react. <br />
+ * Note that if you need search for ONLY given options, not included your typings,
+ * should considering using the `Select` component with `onSearch` prop.
+ */
+declare const AutoComplete: import("react").ForwardRefExoticComponent<AutoCompleteProps & import("react").RefAttributes<HTMLDivElement>>;
+export default AutoComplete;