@miaixz/ui 0.5.0

package/dist/components/tooltip/tooltip.types.d.ts

@@ -0,0 +1,34 @@
+import type { HTMLAttributes, ReactElement, ReactNode } from "react";
+/**
+ * Describes the event and ARIA properties injected into a tooltip child.
+ *
+ * @public
+ */
+export interface MiaixzTooltipChildProps {
+    /**
+     * References the tooltip together with any existing descriptions.
+     */
+    "aria-describedby"?: string;
+}
+/**
+ * Configures concise contextual help associated with one child.
+ *
+ * @public
+ */
+export interface TooltipProps extends Omit<HTMLAttributes<HTMLSpanElement>, "content"> {
+    /**
+     * Supplies the contextual help content.
+     */
+    content: ReactNode;
+    /**
+     * Supplies the single element described by the tooltip.
+     */
+    children: ReactElement<MiaixzTooltipChildProps>;
+    /**
+     * Selects the tooltip placement relative to its child.
+     *
+     * @defaultValue `"top"`
+     */
+    placement?: "top" | "right" | "bottom" | "left";
+}
+//# sourceMappingURL=tooltip.types.d.ts.map

package/dist/components/tooltip/tooltip.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tooltip.types.d.ts","sourceRoot":"","sources":["../../../src/components/tooltip/tooltip.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAErE;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAa,SAAQ,IAAI,CAAC,cAAc,CAAC,eAAe,CAAC,EAAE,SAAS,CAAC;IACpF;;OAEG;IACH,OAAO,EAAE,SAAS,CAAC;IACnB;;OAEG;IACH,QAAQ,EAAE,YAAY,CAAC,uBAAuB,CAAC,CAAC;IAChD;;;;OAIG;IACH,SAAS,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;CACjD"}

package/dist/components/tooltip/tooltip.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tooltip.types.js.map

package/dist/components/tooltip/tooltip.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tooltip.types.js","sourceRoot":"","sources":["../../../src/components/tooltip/tooltip.types.ts"],"names":[],"mappings":"","sourcesContent":["import type { HTMLAttributes, ReactElement, ReactNode } from \"react\";\n\n/**\n * Describes the event and ARIA properties injected into a tooltip child.\n *\n * @public\n */\nexport interface MiaixzTooltipChildProps {\n  /**\n   * References the tooltip together with any existing descriptions.\n   */\n  \"aria-describedby\"?: string;\n}\n\n/**\n * Configures concise contextual help associated with one child.\n *\n * @public\n */\nexport interface TooltipProps extends Omit<HTMLAttributes<HTMLSpanElement>, \"content\"> {\n  /**\n   * Supplies the contextual help content.\n   */\n  content: ReactNode;\n  /**\n   * Supplies the single element described by the tooltip.\n   */\n  children: ReactElement<MiaixzTooltipChildProps>;\n  /**\n   * Selects the tooltip placement relative to its child.\n   *\n   * @defaultValue `\"top\"`\n   */\n  placement?: \"top\" | \"right\" | \"bottom\" | \"left\";\n}\n"]}

package/dist/components/tree-view/index.d.ts

@@ -0,0 +1,3 @@
+export { TreeView } from "./tree-view.js";
+export type { MiaixzTreeViewOwnProps, TreeNode, TreeViewProps } from "./tree-view.types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/components/tree-view/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/tree-view/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,YAAY,EAAE,sBAAsB,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/components/tree-view/index.js

@@ -0,0 +1,2 @@
+export { TreeView } from "./tree-view.js";
+//# sourceMappingURL=index.js.map

package/dist/components/tree-view/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/components/tree-view/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC","sourcesContent":["export { TreeView } from \"./tree-view.js\";\nexport type { MiaixzTreeViewOwnProps, TreeNode, TreeViewProps } from \"./tree-view.types.js\";\n"]}

package/dist/components/tree-view/tree-view.d.ts

@@ -0,0 +1,9 @@
+import { type ReactElement, type RefAttributes } from "react";
+import type { TreeViewProps } from "./tree-view.types.js";
+/**
+ * Renders a business-neutral WAI-ARIA tree view.
+ *
+ * @public
+ */
+export declare const TreeView: <Value = unknown>(props: TreeViewProps<Value> & RefAttributes<HTMLDivElement>) => ReactElement;
+//# sourceMappingURL=tree-view.d.ts.map

package/dist/components/tree-view/tree-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-view.d.ts","sourceRoot":"","sources":["../../../src/components/tree-view/tree-view.tsx"],"names":[],"mappings":"AAAA,OAAO,EAYL,KAAK,YAAY,EACjB,KAAK,aAAa,EACnB,MAAM,OAAO,CAAC;AAOf,OAAO,KAAK,EAAY,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAkjBpE;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAyC,CAAC,KAAK,GAAG,OAAO,EAC5E,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC,GAAG,aAAa,CAAC,cAAc,CAAC,KACxD,YAAY,CAAC"}

package/dist/components/tree-view/tree-view.js

@@ -0,0 +1,573 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from "react";
+import { createMiaixzUiError, MiaixzUiError } from "../../errors/index.js";
+import { useMiaixzLocale } from "../../i18n/index.js";
+import { classNames } from "../../internal/class-names.js";
+import { useMergedRef } from "../../internal/use-merged-ref.js";
+import { Icon } from "../icon/index.js";
+/**
+ * Defines the delay used to combine printable-key tree navigation.
+ */
+const miaixzTreeTypeaheadResetMilliseconds = 500;
+/**
+ * Renders the public generic TreeView implementation.
+ *
+ * @typeParam Value - Consumer-owned value attached to each node.
+ * @param props - Public tree configuration and native root attributes.
+ * @param forwardedRef - Forwarded root div reference.
+ * @returns A keyboard-navigable WAI-ARIA tree.
+ */
+function TreeViewImplementation(props, forwardedRef) {
+    const { nodes, selectionMode = "single", selectedIds, defaultSelectedIds, onSelectedIdsChange, expandedIds, defaultExpandedIds, onExpandedIdsChange, loadChildren, label, className, onBlurCapture, onFocusCapture, ...rootProps } = props;
+    const { t } = useMiaixzLocale();
+    const selectedControlled = selectedIds !== undefined;
+    const expandedControlled = expandedIds !== undefined;
+    validateMiaixzTreeControlledValue(t, selectedControlled, defaultSelectedIds !== undefined, onSelectedIdsChange !== undefined);
+    validateMiaixzTreeControlledValue(t, expandedControlled, defaultExpandedIds !== undefined, onExpandedIdsChange !== undefined);
+    useStableMiaixzTreeControlModes(t, selectedControlled, expandedControlled);
+    const [internalSelectedIds, setInternalSelectedIds] = useState(() => createUniqueMiaixzTreeIds(defaultSelectedIds ?? []));
+    const [internalExpandedIds, setInternalExpandedIds] = useState(() => createUniqueMiaixzTreeIds(defaultExpandedIds ?? []));
+    const [childCache, setChildCache] = useState(() => new Map());
+    const [loadingIds, setLoadingIds] = useState(() => new Set());
+    const [failedIds, setFailedIds] = useState(() => new Set());
+    const [focusedId, setFocusedId] = useState(null);
+    const [fatalError, setFatalError] = useState(null);
+    const rootElementRef = useRef(null);
+    const rootRef = useMergedRef(forwardedRef, rootElementRef);
+    const itemRefs = useRef(new Map());
+    const pendingLoadsRef = useRef(new Map());
+    const childCacheRef = useRef(new Map());
+    const selectedSnapshotRef = useRef(createUniqueMiaixzTreeIds(selectedIds ?? defaultSelectedIds ?? []));
+    const expandedSnapshotRef = useRef(createUniqueMiaixzTreeIds(expandedIds ?? defaultExpandedIds ?? []));
+    const typeaheadRef = useRef("");
+    const typeaheadTimerRef = useRef(undefined);
+    const treeHadFocusRef = useRef(false);
+    const currentSelectedIds = createUniqueMiaixzTreeIds(selectedControlled ? (selectedIds ?? []) : internalSelectedIds);
+    const currentExpandedIds = createUniqueMiaixzTreeIds(expandedControlled ? (expandedIds ?? []) : internalExpandedIds);
+    const selectedSet = useMemo(() => new Set(currentSelectedIds), [currentSelectedIds]);
+    const expandedSet = useMemo(() => new Set(currentExpandedIds), [currentExpandedIds]);
+    const treeIndex = useMemo(() => createMiaixzTreeIndex(t, nodes, childCache), [childCache, nodes, t]);
+    const visibleNodes = useMemo(() => createVisibleMiaixzTreeNodes(nodes, childCache, expandedSet), [childCache, expandedSet, nodes]);
+    const visibleIdSet = useMemo(() => new Set(visibleNodes.map((entry) => entry.node.id)), [visibleNodes]);
+    const resolvedFocusedId = resolveMiaixzTreeFocusedId(focusedId, currentSelectedIds, visibleNodes, visibleIdSet, treeIndex);
+    useEffect(() => {
+        if (selectedControlled)
+            selectedSnapshotRef.current = currentSelectedIds;
+    }, [currentSelectedIds, selectedControlled]);
+    useEffect(() => {
+        if (expandedControlled)
+            expandedSnapshotRef.current = currentExpandedIds;
+    }, [currentExpandedIds, expandedControlled]);
+    useEffect(() => {
+        const reachableIds = treeIndex.ids;
+        let cancelled = false;
+        queueMicrotask(() => {
+            if (cancelled)
+                return;
+            const nextCache = new Map(childCacheRef.current);
+            let changed = false;
+            for (const id of nextCache.keys()) {
+                if (reachableIds.has(id))
+                    continue;
+                nextCache.delete(id);
+                changed = true;
+            }
+            for (const [id, pending] of pendingLoadsRef.current) {
+                if (reachableIds.has(id))
+                    continue;
+                pending.controller.abort();
+                pendingLoadsRef.current.delete(id);
+            }
+            if (changed) {
+                childCacheRef.current = nextCache;
+                setChildCache(nextCache);
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [treeIndex.ids]);
+    useEffect(() => () => {
+        if (typeaheadTimerRef.current !== undefined) {
+            window.clearTimeout(typeaheadTimerRef.current);
+        }
+        for (const pending of pendingLoadsRef.current.values())
+            pending.controller.abort();
+        pendingLoadsRef.current.clear();
+    }, []);
+    useLayoutEffect(() => {
+        if (focusedId !== resolvedFocusedId && resolvedFocusedId !== null && treeHadFocusRef.current) {
+            itemRefs.current.get(resolvedFocusedId)?.focus({ preventScroll: true });
+        }
+    }, [focusedId, resolvedFocusedId]);
+    const emitSelectedIds = useCallback((nextIds) => {
+        const normalizedIds = createUniqueMiaixzTreeIds(nextIds);
+        if (!selectedControlled) {
+            selectedSnapshotRef.current = normalizedIds;
+            setInternalSelectedIds(normalizedIds);
+        }
+        onSelectedIdsChange?.(normalizedIds);
+    }, [onSelectedIdsChange, selectedControlled]);
+    const emitExpandedIds = useCallback((nextIds) => {
+        const normalizedIds = createUniqueMiaixzTreeIds(nextIds);
+        if (!expandedControlled) {
+            expandedSnapshotRef.current = normalizedIds;
+            setInternalExpandedIds(normalizedIds);
+        }
+        onExpandedIdsChange?.(normalizedIds);
+    }, [expandedControlled, onExpandedIdsChange]);
+    const setNodeExpanded = useCallback((nodeId, expanded) => {
+        const currentIds = expandedSnapshotRef.current;
+        const nextIds = expanded
+            ? currentIds.includes(nodeId)
+                ? currentIds
+                : [...currentIds, nodeId]
+            : currentIds.filter((id) => id !== nodeId);
+        emitExpandedIds(nextIds);
+    }, [emitExpandedIds]);
+    const setNodeSelected = useCallback((node) => {
+        if (selectionMode === "none" || node.disabled === true)
+            return;
+        const currentIds = selectedSnapshotRef.current;
+        if (selectionMode === "single") {
+            emitSelectedIds([node.id]);
+            return;
+        }
+        emitSelectedIds(currentIds.includes(node.id)
+            ? currentIds.filter((id) => id !== node.id)
+            : [...currentIds, node.id]);
+    }, [emitSelectedIds, selectionMode]);
+    const focusNode = useCallback((nodeId) => {
+        setFocusedId(nodeId);
+        itemRefs.current.get(nodeId)?.focus({ preventScroll: true });
+    }, []);
+    const loadLazyChildren = useCallback((node) => {
+        if (loadChildren === undefined || node.disabled === true)
+            return;
+        const existing = pendingLoadsRef.current.get(node.id);
+        if (existing !== undefined)
+            return existing.promise;
+        const controller = new AbortController();
+        setLoadingIds((currentIds) => addMiaixzTreeSetValue(currentIds, node.id));
+        setFailedIds((currentIds) => removeMiaixzTreeSetValue(currentIds, node.id));
+        const promise = loadChildren(node, controller.signal)
+            .then((children) => {
+            if (controller.signal.aborted)
+                return;
+            const nextCache = new Map(childCacheRef.current);
+            nextCache.set(node.id, children);
+            createMiaixzTreeIndex(t, nodes, nextCache);
+            childCacheRef.current = nextCache;
+            setChildCache(nextCache);
+            setFailedIds((currentIds) => removeMiaixzTreeSetValue(currentIds, node.id));
+            if (children.length > 0)
+                setNodeExpanded(node.id, true);
+        })
+            .catch((error) => {
+            if (controller.signal.aborted)
+                return;
+            if (error instanceof MiaixzUiError && error.code === "UI_TREE_DUPLICATE_ID") {
+                setFatalError(error);
+                return;
+            }
+            setFailedIds((currentIds) => addMiaixzTreeSetValue(currentIds, node.id));
+        })
+            .finally(() => {
+            const current = pendingLoadsRef.current.get(node.id);
+            if (current?.promise === promise)
+                pendingLoadsRef.current.delete(node.id);
+            if (!controller.signal.aborted) {
+                setLoadingIds((currentIds) => removeMiaixzTreeSetValue(currentIds, node.id));
+            }
+        });
+        pendingLoadsRef.current.set(node.id, { controller, promise });
+        return promise;
+    }, [loadChildren, nodes, setNodeExpanded, t]);
+    const toggleNodeExpanded = useCallback((node) => {
+        if (node.disabled === true)
+            return;
+        if (expandedSnapshotRef.current.includes(node.id)) {
+            setNodeExpanded(node.id, false);
+            return;
+        }
+        const resolvedChildren = resolveMiaixzTreeChildren(node, childCache);
+        if (resolvedChildren !== undefined) {
+            if (resolvedChildren.length > 0)
+                setNodeExpanded(node.id, true);
+            return;
+        }
+        if (node.hasChildren === true)
+            void loadLazyChildren(node);
+    }, [childCache, loadLazyChildren, setNodeExpanded]);
+    const handleTreeItemKeyDown = useCallback((event, entry) => {
+        event.stopPropagation();
+        const visibleIndex = visibleNodes.findIndex((candidate) => candidate.node.id === entry.node.id);
+        if (event.key === "ArrowDown") {
+            event.preventDefault();
+            const next = visibleNodes[Math.min(visibleIndex + 1, visibleNodes.length - 1)];
+            if (next !== undefined)
+                focusNode(next.node.id);
+            return;
+        }
+        if (event.key === "ArrowUp") {
+            event.preventDefault();
+            const previous = visibleNodes[Math.max(visibleIndex - 1, 0)];
+            if (previous !== undefined)
+                focusNode(previous.node.id);
+            return;
+        }
+        if (event.key === "Home") {
+            event.preventDefault();
+            const first = visibleNodes[0];
+            if (first !== undefined)
+                focusNode(first.node.id);
+            return;
+        }
+        if (event.key === "End") {
+            event.preventDefault();
+            const last = visibleNodes[visibleNodes.length - 1];
+            if (last !== undefined)
+                focusNode(last.node.id);
+            return;
+        }
+        if (event.key === "ArrowRight") {
+            event.preventDefault();
+            if (isMiaixzTreeNodeExpandable(entry.node, childCache) && !expandedSet.has(entry.node.id)) {
+                toggleNodeExpanded(entry.node);
+                return;
+            }
+            const next = visibleNodes[visibleIndex + 1];
+            if (expandedSet.has(entry.node.id) && next?.parentId === entry.node.id) {
+                focusNode(next.node.id);
+            }
+            return;
+        }
+        if (event.key === "ArrowLeft") {
+            event.preventDefault();
+            if (expandedSet.has(entry.node.id)) {
+                toggleNodeExpanded(entry.node);
+            }
+            else if (entry.parentId !== null) {
+                focusNode(entry.parentId);
+            }
+            return;
+        }
+        if (event.key === "Enter" || event.key === " ") {
+            event.preventDefault();
+            setNodeSelected(entry.node);
+            return;
+        }
+        if (isMiaixzTreeTypeaheadKey(event)) {
+            typeaheadRef.current += event.key.toLocaleLowerCase();
+            if (typeaheadTimerRef.current !== undefined) {
+                window.clearTimeout(typeaheadTimerRef.current);
+            }
+            typeaheadTimerRef.current = window.setTimeout(() => {
+                typeaheadRef.current = "";
+                typeaheadTimerRef.current = undefined;
+            }, miaixzTreeTypeaheadResetMilliseconds);
+            const match = findMiaixzTreeTypeaheadMatch(visibleNodes, visibleIndex, typeaheadRef.current);
+            if (match !== undefined)
+                focusNode(match.node.id);
+        }
+    }, [childCache, expandedSet, focusNode, setNodeSelected, toggleNodeExpanded, visibleNodes]);
+    const handleFocusCapture = useCallback((event) => {
+        treeHadFocusRef.current = true;
+        onFocusCapture?.(event);
+    }, [onFocusCapture]);
+    const handleBlurCapture = useCallback((event) => {
+        if (!event.currentTarget.contains(event.relatedTarget)) {
+            queueMicrotask(() => {
+                treeHadFocusRef.current =
+                    rootElementRef.current?.contains(document.activeElement) === true;
+            });
+        }
+        onBlurCapture?.(event);
+    }, [onBlurCapture]);
+    /**
+     * Renders one sibling collection and its recursively expanded descendants.
+     *
+     * @param siblings - Ordered sibling nodes to render.
+     * @returns Tree item elements for the supplied sibling collection.
+     */
+    const renderNodes = (siblings) => siblings.map((node) => {
+        const entry = treeIndex.byId.get(node.id);
+        const resolvedChildren = resolveMiaixzTreeChildren(node, childCache);
+        const expandable = isMiaixzTreeNodeExpandable(node, childCache);
+        const expanded = expandable && expandedSet.has(node.id);
+        const selected = selectedSet.has(node.id);
+        const loading = loadingIds.has(node.id);
+        const failed = failedIds.has(node.id);
+        const itemState = loading
+            ? "loading"
+            : failed
+                ? "error"
+                : expanded
+                    ? "expanded"
+                    : "collapsed";
+        return (_jsxs("div", { ref: (element) => {
+                if (element === null)
+                    itemRefs.current.delete(node.id);
+                else
+                    itemRefs.current.set(node.id, element);
+            }, role: "treeitem", tabIndex: node.id === resolvedFocusedId ? 0 : -1, "aria-level": entry.level, "aria-posinset": entry.position, "aria-setsize": entry.setSize, "aria-label": getMiaixzTreeLabelText(node.label) || undefined, "aria-expanded": expandable ? expanded : undefined, "aria-selected": selectionMode === "none" ? undefined : selected, "aria-disabled": node.disabled || undefined, "aria-busy": loading || undefined, className: "miaixz-tree-view-item", "data-state": itemState, "data-disabled": node.disabled || undefined, onFocus: (event) => {
+                event.stopPropagation();
+                setFocusedId(node.id);
+            }, onKeyDown: (event) => handleTreeItemKeyDown(event, entry), children: [_jsxs("div", { className: "miaixz-tree-view-row", onClick: () => {
+                        focusNode(node.id);
+                        setNodeSelected(node);
+                    }, children: [_jsx("span", { className: "miaixz-tree-view-expander", "data-state": expandable ? (expanded ? "expanded" : "collapsed") : "leaf", onClick: (event) => {
+                                event.stopPropagation();
+                                focusNode(node.id);
+                                if (expandable)
+                                    toggleNodeExpanded(node);
+                            }, children: loading ? (_jsx(Icon, { name: "LoaderCircle", size: "control", className: "miaixz-icon-spin" })) : expandable ? (_jsx(Icon, { name: expanded ? "ChevronDown" : "ChevronRight", size: "control" })) : null }), _jsx("span", { className: "miaixz-tree-view-label", children: node.label }), selected && selectionMode !== "none" && (_jsx(Icon, { name: "Check", size: "control", className: "miaixz-tree-view-selection" }))] }), failed && (_jsxs("div", { className: "miaixz-tree-view-error", role: "alert", children: [_jsx("span", { children: t("ui.tree.loadError") }), _jsxs("button", { type: "button", className: "miaixz-tree-view-retry", onClick: (event) => {
+                                event.stopPropagation();
+                                void loadLazyChildren(node);
+                            }, children: [_jsx(Icon, { name: "RotateCcw", size: "indicator" }), t("ui.action.retry")] })] })), expanded && resolvedChildren !== undefined && resolvedChildren.length > 0 && (_jsx("div", { role: "group", className: "miaixz-tree-view-group", children: renderNodes(resolvedChildren) }))] }, node.id));
+    });
+    if (fatalError !== null)
+        throw fatalError;
+    return (_jsx("div", { ...rootProps, ref: rootRef, role: "tree", "aria-label": label, "aria-multiselectable": selectionMode === "multiple" || undefined, className: classNames("miaixz-tree-view", className), onFocusCapture: handleFocusCapture, onBlurCapture: handleBlurCapture, children: renderNodes(nodes) }));
+}
+/**
+ * Renders a business-neutral WAI-ARIA tree view.
+ *
+ * @public
+ */
+export const TreeView = forwardRef(TreeViewImplementation);
+/**
+ * Validates one selected or expanded controlled-value contract.
+ *
+ * @param translate - Active localized message resolver.
+ * @param controlled - Whether a controlled value was supplied.
+ * @param hasDefault - Whether an uncontrolled default was supplied.
+ * @param hasChangeHandler - Whether requested changes can be observed.
+ */
+function validateMiaixzTreeControlledValue(translate, controlled, hasDefault, hasChangeHandler) {
+    if (controlled && (!hasChangeHandler || hasDefault)) {
+        throw createMiaixzUiError(translate, {
+            code: "UI_CONTROLLED_VALUE_INVALID",
+            messageKey: "ui.error.controlled.valueInvalid",
+        });
+    }
+}
+/**
+ * Freezes selected and expanded control modes for the mounted lifetime.
+ *
+ * @param translate - Active localized message resolver.
+ * @param selectedControlled - Current selection control mode.
+ * @param expandedControlled - Current expansion control mode.
+ */
+function useStableMiaixzTreeControlModes(translate, selectedControlled, expandedControlled) {
+    const [initialModes] = useState({
+        selected: selectedControlled,
+        expanded: expandedControlled,
+    });
+    if (initialModes.selected !== selectedControlled ||
+        initialModes.expanded !== expandedControlled) {
+        throw createMiaixzUiError(translate, {
+            code: "UI_CONTROL_MODE_CHANGED",
+            messageKey: "ui.error.controlled.modeChanged",
+        });
+    }
+}
+/**
+ * Produces an ordered identifier list without duplicate values.
+ *
+ * @param ids - Source identifier collection.
+ * @returns Ordered unique identifier collection.
+ */
+function createUniqueMiaixzTreeIds(ids) {
+    return [...new Set(ids)];
+}
+/**
+ * Builds the complete reachable tree index and validates identifier uniqueness.
+ *
+ * @typeParam Value - Consumer-owned value attached to each node.
+ * @param translate - Active localized message resolver.
+ * @param nodes - Root node collection.
+ * @param childCache - Successful lazy child results.
+ * @returns Complete immutable structural index.
+ */
+function createMiaixzTreeIndex(translate, nodes, childCache) {
+    const byId = new Map();
+    /**
+     * Visits one sibling collection in source order.
+     *
+     * @param siblings - Ordered siblings at the current depth.
+     * @param parentId - Parent identifier or null for roots.
+     * @param level - One-based ARIA depth.
+     */
+    function visit(siblings, parentId, level) {
+        siblings.forEach((node, index) => {
+            if (byId.has(node.id)) {
+                throw createMiaixzUiError(translate, {
+                    code: "UI_TREE_DUPLICATE_ID",
+                    messageKey: "ui.error.tree.duplicateId",
+                    details: { duplicateId: node.id },
+                });
+            }
+            byId.set(node.id, {
+                node,
+                parentId,
+                level,
+                position: index + 1,
+                setSize: siblings.length,
+            });
+            const children = resolveMiaixzTreeChildren(node, childCache);
+            if (children !== undefined)
+                visit(children, node.id, level + 1);
+        });
+    }
+    visit(nodes, null, 1);
+    return { byId, ids: new Set(byId.keys()) };
+}
+/**
+ * Creates the ordered visible-node collection for current expansion state.
+ *
+ * @typeParam Value - Consumer-owned value attached to each node.
+ * @param nodes - Root node collection.
+ * @param childCache - Successful lazy child results.
+ * @param expandedIds - Currently expanded identifiers.
+ * @returns Visible nodes in depth-first keyboard order.
+ */
+function createVisibleMiaixzTreeNodes(nodes, childCache, expandedIds) {
+    const result = [];
+    /**
+     * Appends one sibling collection and expanded descendants.
+     *
+     * @param siblings - Ordered siblings at the current depth.
+     * @param parentId - Parent identifier or null for roots.
+     * @param level - One-based ARIA depth.
+     */
+    function append(siblings, parentId, level) {
+        siblings.forEach((node, index) => {
+            result.push({
+                node,
+                parentId,
+                level,
+                position: index + 1,
+                setSize: siblings.length,
+            });
+            const children = resolveMiaixzTreeChildren(node, childCache);
+            if (expandedIds.has(node.id) && children !== undefined && children.length > 0) {
+                append(children, node.id, level + 1);
+            }
+        });
+    }
+    append(nodes, null, 1);
+    return result;
+}
+/**
+ * Resolves static or successfully loaded children for one node.
+ *
+ * @typeParam Value - Consumer-owned value attached to the node.
+ * @param node - Node whose children are requested.
+ * @param childCache - Successful lazy child results.
+ * @returns Loaded child collection, including an empty result, or undefined.
+ */
+function resolveMiaixzTreeChildren(node, childCache) {
+    return node.children ?? childCache.get(node.id);
+}
+/**
+ * Reports whether one node currently exposes an expansion affordance.
+ *
+ * @typeParam Value - Consumer-owned value attached to the node.
+ * @param node - Candidate tree node.
+ * @param childCache - Successful lazy child results.
+ * @returns Whether the node has visible or loadable children.
+ */
+function isMiaixzTreeNodeExpandable(node, childCache) {
+    const children = resolveMiaixzTreeChildren(node, childCache);
+    return children === undefined ? node.hasChildren === true : children.length > 0;
+}
+/**
+ * Resolves the sole visible roving-tabindex node.
+ *
+ * @typeParam Value - Consumer-owned value attached to each node.
+ * @param focusedId - Last explicitly focused identifier.
+ * @param selectedIds - Ordered selected identifiers.
+ * @param visibleNodes - Current depth-first visible nodes.
+ * @param visibleIds - Set form of the visible identifiers.
+ * @param treeIndex - Complete reachable tree index.
+ * @returns Visible focused identifier or null for an empty tree.
+ */
+function resolveMiaixzTreeFocusedId(focusedId, selectedIds, visibleNodes, visibleIds, treeIndex) {
+    if (focusedId !== null) {
+        let candidate = focusedId;
+        while (candidate !== null) {
+            if (visibleIds.has(candidate))
+                return candidate;
+            candidate = treeIndex.byId.get(candidate)?.parentId ?? null;
+        }
+    }
+    const selected = selectedIds.find((id) => visibleIds.has(id));
+    return selected ?? visibleNodes[0]?.node.id ?? null;
+}
+/**
+ * Adds one value to an immutable set snapshot.
+ *
+ * @param values - Current set snapshot.
+ * @param value - Value to add.
+ * @returns Original or updated set snapshot.
+ */
+function addMiaixzTreeSetValue(values, value) {
+    if (values.has(value))
+        return values;
+    const nextValues = new Set(values);
+    nextValues.add(value);
+    return nextValues;
+}
+/**
+ * Removes one value from an immutable set snapshot.
+ *
+ * @param values - Current set snapshot.
+ * @param value - Value to remove.
+ * @returns Original or updated set snapshot.
+ */
+function removeMiaixzTreeSetValue(values, value) {
+    if (!values.has(value))
+        return values;
+    const nextValues = new Set(values);
+    nextValues.delete(value);
+    return nextValues;
+}
+/**
+ * Reports whether a keyboard event contains one printable typeahead character.
+ *
+ * @param event - Tree-item keyboard event.
+ * @returns Whether the key can participate in typeahead navigation.
+ */
+function isMiaixzTreeTypeaheadKey(event) {
+    return (event.key.length === 1 && event.key !== " " && !event.altKey && !event.ctrlKey && !event.metaKey);
+}
+/**
+ * Finds the next visible node matching the current typeahead buffer.
+ *
+ * @typeParam Value - Consumer-owned value attached to each node.
+ * @param visibleNodes - Current depth-first visible nodes.
+ * @param currentIndex - Current visible node index.
+ * @param query - Normalized accumulated typeahead query.
+ * @returns Next matching node or undefined.
+ */
+function findMiaixzTreeTypeaheadMatch(visibleNodes, currentIndex, query) {
+    for (let offset = 1; offset <= visibleNodes.length; offset += 1) {
+        const candidate = visibleNodes[(currentIndex + offset) % visibleNodes.length];
+        if (candidate !== undefined &&
+            getMiaixzTreeLabelText(candidate.node.label).toLocaleLowerCase().startsWith(query)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+/**
+ * Extracts safe typeahead text from primitive React labels.
+ *
+ * @param label - Public React node label.
+ * @returns String or numeric label text, otherwise an empty string.
+ */
+function getMiaixzTreeLabelText(label) {
+    return typeof label === "string" || typeof label === "number" ? String(label) : "";
+}
+//# sourceMappingURL=tree-view.js.map