@rainbow-oh/yee-c 0.4.2 → 0.4.4

package/dist/cjs/Tabs/tabs.js

@@ -147,7 +147,9 @@ var Tabs = (baseprops) => {
       return;
     }
     setMergedActiveKey(key);
-    onChange == null ? void 0 : onChange(key);
+    if (key !== mergedActiveKey) {
+      onChange == null ? void 0 : onChange(key);
+    }
   };
   const contextValue = (0, import_react.useMemo)(
     () => ({

package/dist/cjs/Tag/demo/checkable.js

@@ -40,6 +40,7 @@ var checkable_default = () => {
     import_yee_c.Tag,
     {
       checkable: true,
+      variant: "outlined",
       checked,
       onChange: (checked2) => setChecked(checked2)
     },

package/dist/cjs/Tag/tag.js

@@ -112,7 +112,6 @@ var Tag = (0, import_react.forwardRef)(
     };
     const cls = (0, import_clsx.default)(
       prefixCls,
-      [`${prefixCls}-${variant}`],
       {
         [`${prefixCls}-${status}`]: status,
         [`${prefixCls}-dashed`]: dashed,
@@ -120,6 +119,7 @@ var Tag = (0, import_react.forwardRef)(
         [`${prefixCls}-${size}`]: size,
         [`${prefixCls}-checkable`]: checkable
       },
+      [`${prefixCls}-${variant}`],
       className
     );
     const renderClose = () => closable ? /* @__PURE__ */ import_react.default.createElement(

package/dist/cjs/TextArea/textarea.js

@@ -106,7 +106,6 @@ var TextArea = (0, import_react.forwardRef)(
       value,
       defaultValue
     });
-    console.log("mergedValue: ", mergedValue, value);
     (0, import_react.useEffect)(() => {
       const ele = componentRef.current;
       if (ele && autoSize) {

package/dist/cjs/Trigger/trigger.js

@@ -187,7 +187,7 @@ var Trigger = (baseprops) => {
   return /* @__PURE__ */ import_react.default.createElement(
     import_trigger.default,
     __spreadProps(__spreadValues(__spreadProps(__spreadValues({}, rest), {
-      prefixCls: "yee-trigger",
+      prefixCls,
       mouseEnterDelay,
       mouseLeaveDelay,
       arrow,

package/dist/cjs/style/color.css

@@ -30,7 +30,7 @@
   --yee-text-color-description: #7c7c7c;
   --yee-text-color-disabled: #bfbfbf;
   --yee-text-color-highlight: #f58220;
-  --yee-text-color-auxiliary: #f5f5f5;
+  --yee-text-color-auxiliary: #d1d1d1;
   --yee-color-split: #e7e7e7;
   --yee-border-color: #cbd6e2;
   --yee-border-color-hover-focus: #75b9f0;

package/dist/cjs/style/size.css

@@ -278,6 +278,14 @@
   --yee-input-border-width: 1px;
   --yee-input-suffix-gap: 4px;
   --yee-input-clear-padding: 1px;
+  --yee-input-small-font-size: 12px;
+  --yee-input-small-line-height: 20px;
+  --yee-input-small-height: 24px;
+  --yee-input-small-padding: 0 6px;
+  --yee-input-large-font-size: 16px;
+  --yee-input-large-line-height: 24px;
+  --yee-input-large-height: 40px;
+  --yee-input-large-padding: 4px 12px;
 
   /* --JsonViewer-- */
   --yee-json-view-font-size: 14px;
@@ -651,7 +659,7 @@
   --yee-table-bordered-cell-border-width: 1px;
   --yee-table-bordered-thead-border-width: 1px;
   --yee-table-thead-action-gap: 8px;
-  --yee-table-filter-popup-padding: 16px;
+  --yee-table-filter-popup-padding: 8px;
   --yee-table-content-border-radius: 6px 6px 0 0;
   --yee-table-cell-padding: 13px 16px;
   --yee-table-cell-line-height: 22px;
@@ -740,7 +748,7 @@
   --yee-tag-font-size: 12px;
   --yee-tag-line-height: 22px;
   --yee-tag-border-width: 1px;
-  --yee-tag-border-radius: 2px;
+  --yee-tag-border-radius: 4px;
   --yee-tag-icon-margin-left: 4px;
   --yee-tag-small-height: 16px;
   --yee-tag-large-height: 28px;

package/dist/cjs/style/themes.css

@@ -1,7 +1,7 @@
 /*!
  * @rainbow-oh/yee-c CSS Variables
  * Auto-generated, do not edit manually
- * Generated on 2026-07-01T03:21:30.989Z
+ * Generated on 2026-07-03T02:41:11.107Z
  */
 
 /* ========== color.blue.css ========== */

package/dist/cjs/style/variables.css

@@ -1,7 +1,7 @@
 /*!
  * @rainbow-oh/yee-c CSS Variables
  * Auto-generated, do not edit manually
- * Generated on 2026-07-01T03:21:30.989Z
+ * Generated on 2026-07-03T02:41:11.107Z
  */
 
 /* ========== color.css ========== */
@@ -37,7 +37,7 @@
   --yee-text-color-description: #7c7c7c;
   --yee-text-color-disabled: #bfbfbf;
   --yee-text-color-highlight: #f58220;
-  --yee-text-color-auxiliary: #f5f5f5;
+  --yee-text-color-auxiliary: #d1d1d1;
   --yee-color-split: #e7e7e7;
   --yee-border-color: #cbd6e2;
   --yee-border-color-hover-focus: #75b9f0;
@@ -1396,6 +1396,14 @@
   --yee-input-border-width: 1px;
   --yee-input-suffix-gap: 4px;
   --yee-input-clear-padding: 1px;
+  --yee-input-small-font-size: 12px;
+  --yee-input-small-line-height: 20px;
+  --yee-input-small-height: 24px;
+  --yee-input-small-padding: 0 6px;
+  --yee-input-large-font-size: 16px;
+  --yee-input-large-line-height: 24px;
+  --yee-input-large-height: 40px;
+  --yee-input-large-padding: 4px 12px;
 
   /* --JsonViewer-- */
   --yee-json-view-font-size: 14px;
@@ -1769,7 +1777,7 @@
   --yee-table-bordered-cell-border-width: 1px;
   --yee-table-bordered-thead-border-width: 1px;
   --yee-table-thead-action-gap: 8px;
-  --yee-table-filter-popup-padding: 16px;
+  --yee-table-filter-popup-padding: 8px;
   --yee-table-content-border-radius: 6px 6px 0 0;
   --yee-table-cell-padding: 13px 16px;
   --yee-table-cell-line-height: 22px;
@@ -1858,7 +1866,7 @@
   --yee-tag-font-size: 12px;
   --yee-tag-line-height: 22px;
   --yee-tag-border-width: 1px;
-  --yee-tag-border-radius: 2px;
+  --yee-tag-border-radius: 4px;
   --yee-tag-icon-margin-left: 4px;
   --yee-tag-small-height: 16px;
   --yee-tag-large-height: 28px;

package/dist/cjs/version.d.ts

@@ -3,4 +3,4 @@ declare global {
         __yee_c_version__: string;
     }
 }
-export declare const version = "0.4.2";
+export declare const version = "0.4.4";

package/dist/cjs/version.js

@@ -22,7 +22,7 @@ __export(version_exports, {
   version: () => version
 });
 module.exports = __toCommonJS(version_exports);
-var version = "0.4.2";
+var version = "0.4.4";
 if (typeof window !== "undefined") {
   window.__yee_c_version__ = version;
 }

package/dist/esm/Cascader/cascader.js

@@ -24,7 +24,7 @@ import isEqual from "../utils/isEqual";
 import mergeContextToProps from "../utils/mergeContextToProps";
 import Column from "./column";
 import SearchList from "./search-list";
-import { changeToView, flattenOptions, hasChild } from "./utils";
+import { changeToView, flattenOptions, getChildren, isSamePrefixPath, pathToUid } from "./utils";
 import "./style/index.less";
 export var CascaderCtx = /*#__PURE__*/createContext({});
 var Cascader = function Cascader(baseprops) {
@@ -39,7 +39,8 @@ var Cascader = function Cascader(baseprops) {
     _props$placement = props.placement,
     placement = _props$placement === void 0 ? 'bottomLeft' : _props$placement,
     popupClassName = props.popupClassName,
-    searchable = props.searchable,
+    _props$searchable = props.searchable,
+    searchable = _props$searchable === void 0 ? true : _props$searchable,
     _props$fieldNames = props.fieldNames,
     fieldNames = _props$fieldNames === void 0 ? {
       label: 'label',
@@ -104,8 +105,6 @@ var Cascader = function Cascader(baseprops) {
       return;
     }
     var _changeToView = changeToView(currentValue || [], flatOptions, {
-        needNext: true,
-        // Set to true to expand to full path
         multiple: multiple
       }),
       _changeToView2 = _slicedToArray(_changeToView, 2),
@@ -130,9 +129,9 @@ var Cascader = function Cascader(baseprops) {
 
   // node mouse evt
   var onNodeMouseEnter = function onNodeMouseEnter(item, level) {
-    if (expandTrigger === 'hover' && hasChild(item)) {
+    if (expandTrigger === 'hover' && !item.isLeaf) {
       var queue = columns.slice(0, level + 1);
-      queue.push(item.children);
+      queue.push(getChildren(flatOptions, item.uid));
       setColumns(queue);
       // Also update expandedPath to maintain highlight state
       setExpandedPath(function (prev) {
@@ -145,24 +144,23 @@ var Cascader = function Cascader(baseprops) {
   };
 
   // Helper function to get all descendant paths of a node
-  // Note: For very deep trees, consider adding maxDepth parameter or prevent stack overflow
   var getAllDescendantPaths = useCallback(function (node) {
     var maxDepth = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 100;
     var paths = [];
     var traverse = function traverse(currentNode, depth) {
       if (depth > maxDepth) return; // Prevent stack overflow
-      if (!hasChild(currentNode)) {
+      if (currentNode.isLeaf) {
         paths.push(currentNode.path);
         return;
       }
-      var children = currentNode.children;
+      var children = getChildren(flatOptions, currentNode.uid);
       children.forEach(function (child) {
         return traverse(child, depth + 1);
       });
     };
     traverse(node, 0);
     return paths;
-  }, []);
+  }, [flatOptions]);
 
   // cascader node click
   var onItemClick = useCallback(function (item) {
@@ -180,18 +178,14 @@ var Cascader = function Cascader(baseprops) {
       var isSelected = currentValue.some(function (v) {
         return isEqual(v, item.path);
       });
-      if (hasChild(item)) {
+      if (!item.isLeaf) {
         // Parent node: select/deselect all descendants
         var descendantPaths = getAllDescendantPaths(item, 50); // Limit to depth 50 to prevent performance issues
-        var descendantPathStrs = descendantPaths.map(function (p) {
-          return p.join('-');
-        });
 
         // Filter out all descendant paths from current value
         var filteredValue = currentValue.filter(function (v) {
-          var pathStr = v.join('-');
-          return !descendantPathStrs.some(function (descPathStr) {
-            return pathStr.startsWith(descPathStr);
+          return !descendantPaths.some(function (descPath) {
+            return isSamePrefixPath(descPath, v);
           });
         });
         if (!isSelected) {
@@ -201,8 +195,7 @@ var Cascader = function Cascader(baseprops) {
         newValue = filteredValue;
         newOpts = filteredValue.map(function (path) {
           return path.map(function (_, i) {
-            var uid = path.slice(0, i + 1).join('-');
-            return nodeMap.get(uid);
+            return nodeMap.get(pathToUid(path.slice(0, i + 1)));
           });
         });
       } else {
@@ -216,8 +209,7 @@ var Cascader = function Cascader(baseprops) {
         }
         newOpts = newValue.map(function (path) {
           return path.map(function (_, i) {
-            var uid = path.slice(0, i + 1).join('-');
-            return nodeMap.get(uid);
+            return nodeMap.get(pathToUid(path.slice(0, i + 1)));
           });
         });
       }
@@ -225,22 +217,18 @@ var Cascader = function Cascader(baseprops) {
     } else if (shouldSelect) {
       // Single select or non-checkable multi-select
       newValue = multiple ? [].concat(_toConsumableArray(mergedValue), [item.path]) : item.path;
-      newOpts = multiple ? [].concat(_toConsumableArray(mergedValue.map(function (item) {
-        var vs = item;
-        var arr = vs.map(function (_, i) {
-          return vs.slice(0, i + 1).join('-');
-        });
-        return arr.map(function (uid) {
-          return nodeMap.get(uid);
+      newOpts = multiple ? [].concat(_toConsumableArray(mergedValue.map(function (path) {
+        var vs = path;
+        return vs.map(function (_, i) {
+          return nodeMap.get(pathToUid(vs.slice(0, i + 1)));
         });
-      })), [[item.path.map(function (_, i) {
-        var uid = item.path.slice(0, i + 1).join('-');
-        return nodeMap.get(uid);
-      })]]) : flatOptions.filter(function (opt) {
-        var arr = item.path.map(function (_, i) {
-          return item.path.slice(0, i + 1).join('-');
+      })), [item.path.map(function (_, i) {
+        return nodeMap.get(pathToUid(item.path.slice(0, i + 1)));
+      })]) : flatOptions.filter(function (opt) {
+        var ancestors = item.path.map(function (_, i) {
+          return pathToUid(item.path.slice(0, i + 1));
         });
-        return arr.includes(opt.uid);
+        return ancestors.includes(opt.uid);
       });
       changed = true;
     } else {
@@ -284,7 +272,7 @@ var Cascader = function Cascader(baseprops) {
       _props$onlyParentNode = props.onlyParentNode,
       onlyParentNode = _props$onlyParentNode === void 0 ? false : _props$onlyParentNode;
     var formatKey = function formatKey(val) {
-      return val.join('-');
+      return pathToUid(val);
     };
     var rawValues = [];
     if (multiple) {
@@ -297,31 +285,26 @@ var Cascader = function Cascader(baseprops) {
     // Filter values based on onlyParentNode option
     var displayValues = rawValues;
     if (multiple && onlyParentNode) {
-      // Find parent nodes that have all children selected
-      var parentIds = [];
-      var childPathStrs = new Set(rawValues.map(function (v) {
-        return v.join('-');
-      }));
+      // Find parent nodes that have all (direct) children selected
+      var selectedPathKeys = new Set(rawValues.map(pathToUid));
+      var parentPaths = [];
 
       // Check each node to see if it's a fully selected parent
-      nodeMap.forEach(function (node, uid) {
-        if (hasChild(node)) {
-          var _node$children;
-          var allChildrenSelected = (_node$children = node.children) === null || _node$children === void 0 ? void 0 : _node$children.every(function (child) {
-            return childPathStrs.has(child.path.join('-'));
+      nodeMap.forEach(function (node) {
+        if (!node.isLeaf) {
+          var allChildrenSelected = getChildren(flatOptions, node.uid).every(function (child) {
+            return selectedPathKeys.has(pathToUid(child.path));
           });
           if (allChildrenSelected) {
-            parentIds.push(uid);
+            parentPaths.push(node.path);
           }
         }
       });
 
       // Filter out child nodes whose parent is fully selected
       displayValues = rawValues.filter(function (path) {
-        var pathStr = path.join('-');
-        // Keep this path if it's not a child of any fully selected parent
-        return !parentIds.some(function (parentId) {
-          return pathStr.startsWith(parentId + '-');
+        return !parentPaths.some(function (parentPath) {
+          return isSamePrefixPath(parentPath, path);
         });
       });
     }
@@ -338,8 +321,8 @@ var Cascader = function Cascader(baseprops) {
             options: opts
           });
         } else {
-          var _opts$$source, _opts, _source;
-          var source = (_opts$$source = (_opts = opts[opts.length - 1]) === null || _opts === void 0 ? void 0 : _opts.$source) !== null && _opts$$source !== void 0 ? _opts$$source : opts[opts.length - 1];
+          var _opts, _source;
+          var source = (_opts = opts[opts.length - 1]) === null || _opts === void 0 ? void 0 : _opts.$source;
           label = (_source = source === null || source === void 0 ? void 0 : source[optionLabelProp]) !== null && _source !== void 0 ? _source : '';
         }
       } else if (fullNode) {
@@ -359,12 +342,17 @@ var Cascader = function Cascader(baseprops) {
       options: displayOptions,
       selectedKeys: selectedKeys
     };
-  }, [multiple, mergedValue, nodeMap, optionLabelProp, props.fullNode, props.onlyParentNode]);
+  }, [multiple, mergedValue, nodeMap, flatOptions, optionLabelProp, props.fullNode, props.onlyParentNode]);
 
   // visible change
   var onVisibleChange = function onVisibleChange(newVisible) {
     popupVisible.current = newVisible;
   };
+  var handleClear = function handleClear() {
+    setSearchValue('');
+    setMergedValue([]);
+    onChange === null || onChange === void 0 || onChange([], []);
+  };
 
   // Performance Note: For large datasets (1000+ options), consider:
   // 1. Adding debounce to the search input
@@ -379,7 +367,11 @@ var Cascader = function Cascader(baseprops) {
     try {
       for (_iterator.s(); !(_step = _iterator.n()).done;) {
         var item = _step.value;
-        var text = String(item.label);
+        // Match against the full breadcrumb (e.g. "A / B / C") so that:
+        //  - searching a parent label surfaces its descendants,
+        //  - the result row shows the full path to disambiguate duplicate leaf
+        //    labels across different parents.
+        var text = item.labelPath.join(' / ');
         var textLower = text.toLowerCase();
         if (textLower.includes(lowStr)) {
           var matches = [];
@@ -427,7 +419,8 @@ var Cascader = function Cascader(baseprops) {
       searchable: searchable,
       mode: multiple ? 'multiple' : undefined,
       value: searchValue,
-      onSearch: handleSearch
+      onSearch: handleSearch,
+      onClear: handleClear
     }));
   };
   var renderPopup = function renderPopup() {

package/dist/esm/Cascader/interface.d.ts

@@ -15,11 +15,27 @@ export type FieldNames = {
     value: string;
     children: string;
 };
-export type FlattenOption = Option & {
+/**
+ * Flattened representation of a tree node.
+ *
+ * Deliberately a concrete type (not `Option & ...`) so that:
+ *  - `.label` / `.value` / `.isLeaf` resolve to their precise types (an index
+ *    signature on `Option` would otherwise widen them to `unknown`),
+ *  - `.children` is a compile error — flattened nodes intentionally do not
+ *    carry children; use `getChildren(data, uid)` instead.
+ * Dynamic/extra-field access should go through `$source` (the raw node).
+ */
+export type FlattenOption = {
+    $source: Option;
+    label: string;
+    value: string | number;
     pid: string;
     uid: string;
     path: Array<string | number>;
-    $source: Option;
+    labelPath: string[];
+    level: number;
+    isLeaf: boolean;
+    disabled?: boolean;
 };
 export type NodeProps = FlattenOption & {
     level: number;
@@ -87,6 +103,7 @@ export interface CascaderProps extends Omit<SelectorProps, 'options' | 'value' |
     multiple?: boolean;
     /**
      * Is it searchable
+     * @default true
      */
     searchable?: boolean;
     /**

package/dist/esm/Cascader/node.js

@@ -15,14 +15,14 @@ import Checkbox from "../Checkbox";
 import Spin from "../Spin";
 import isEqual from "../utils/isEqual";
 import { CascaderCtx } from "./cascader";
-import { hasChild, isHalfChecked } from "./utils";
+import { getChildren, isHalfChecked } from "./utils";
 var Node = function Node(props) {
   var _expandedPath$level;
   var uid = props.uid,
     value = props.value,
     disabled = props.disabled,
     label = props.label,
-    children = props.children,
+    $source = props.$source,
     isLeaf = props.isLeaf,
     path = props.path,
     level = props.level;
@@ -33,9 +33,10 @@ var Node = function Node(props) {
     mergedValue = _useContext.mergedValue,
     loadData = _useContext.loadData,
     nodeMap = _useContext.nodeMap,
+    flatOptions = _useContext.flatOptions,
     onNodeMouseEnter = _useContext.onNodeMouseEnter,
     onItemClick = _useContext.onItemClick;
-  var isParent = hasChild(props);
+  var isParent = !isLeaf;
 
   /**
    * 0: not load
@@ -57,11 +58,7 @@ var Node = function Node(props) {
     if (loadData && isLeaf === false) {
       var _loadData;
       setLoad(1);
-      (_loadData = loadData({
-        label: label,
-        value: value,
-        children: children
-      })) === null || _loadData === void 0 || _loadData.then(function () {
+      (_loadData = loadData($source)) === null || _loadData === void 0 || _loadData.then(function () {
         setLoad(2);
       }).catch(function () {
         setLoad(0);
@@ -83,12 +80,12 @@ var Node = function Node(props) {
   var _useMemo = useMemo(function () {
       var currentNode = nodeMap.get(uid);
       if (!multiple || !currentNode || !isParent) return [false, false];
-      return isHalfChecked(mergedValue, currentNode);
-    }, [nodeMap, uid, mergedValue, isParent, multiple]),
+      return isHalfChecked(mergedValue, currentNode, getChildren(flatOptions, uid));
+    }, [nodeMap, uid, mergedValue, flatOptions, isParent, multiple]),
     _useMemo2 = _slicedToArray(_useMemo, 2),
     checkedAll = _useMemo2[0],
     indeterminate = _useMemo2[1];
-  var clsName = clsx("".concat(prefixCls, "-menu-item"), _defineProperty(_defineProperty(_defineProperty({}, "".concat(prefixCls, "-menu-item-expand"), hasChild(props)), "".concat(prefixCls, "-menu-item-disabled"), disabled), "active", ((_expandedPath$level = expandedPath[level]) === null || _expandedPath$level === void 0 ? void 0 : _expandedPath$level.key) === uid), "".concat(prefixCls, "-menu-item-").concat(level));
+  var clsName = clsx("".concat(prefixCls, "-menu-item"), _defineProperty(_defineProperty(_defineProperty({}, "".concat(prefixCls, "-menu-item-expand"), !isLeaf), "".concat(prefixCls, "-menu-item-disabled"), disabled), "active", ((_expandedPath$level = expandedPath[level]) === null || _expandedPath$level === void 0 ? void 0 : _expandedPath$level.key) === uid), "".concat(prefixCls, "-menu-item-").concat(level));
   var handleMouseEnter = function handleMouseEnter() {
     if (disabled) return;
     onNodeMouseEnter(props, level);

package/dist/esm/Cascader/search-list.js

@@ -14,7 +14,8 @@ var SearchList = function SearchList(props) {
   return /*#__PURE__*/React.createElement("ul", {
     className: "".concat(prefixCls, "-filter-menu")
   }, items.length ? items.map(function (item) {
-    var title = item.data.title || item.data.label;
+    var _item$data$$source;
+    var title = ((_item$data$$source = item.data.$source) === null || _item$data$$source === void 0 ? void 0 : _item$data$$source.title) || item.data.labelPath.join(' / ');
     return /*#__PURE__*/React.createElement("li", {
       className: "".concat(prefixCls, "-filter-menu-item"),
       title: typeof title === 'string' ? title : String(title),

package/dist/esm/Cascader/utils/index.d.ts

@@ -7,23 +7,58 @@ import { FieldNames, FlattenOption } from '../interface';
  */
 export declare function hasChild(data: Record<string, any>, childrenField?: string): any;
 /**
- * Populate data into input fields and dropdown lists from a value array
- * @param arr - The value array representing the selected path
+ * Separator used to build a node's `uid` from its value path. A control
+ * character is used on purpose so it can never appear inside a user value —
+ * this prevents collisions like value `"a-1"` vs path `["a", "1"]` that a plain
+ * `'-'` separator would produce.
+ */
+export declare const UID_SEP = "\u0001";
+/**
+ * Build the canonical uid for a value path. Use this everywhere a path needs
+ * to be turned into a key (nodeMap lookups, selected keys, comparisons) so the
+ * format stays consistent with the `uid`/`pid` produced by `flattenOptions`.
+ * @param path - The value path
+ */
+export declare const pathToUid: (path: Array<string | number>) => string;
+/**
+ * Get the direct flattened children of the node identified by `uid`.
+ *
+ * Flattened nodes intentionally do not carry a `children` reference (it used to
+ * point at the raw, un-flattened subtree and caused type lies). Derive children
+ * from the flat list via `pid` instead — single source of truth.
+ * @param data - The flattened options data
+ * @param uid - The parent node's uid
+ */
+export declare const getChildren: (data: Array<FlattenOption>, uid: string) => FlattenOption[];
+/**
+ * Reconstruct cascade columns and the highlight path from a value path.
+ *
+ * Walks the flattened options level by level, matching each value segment
+ * against the correct parent column via `pid` + `value`. Returns:
+ *  - `queue`: the columns to render (column 0 = root, then each matched
+ *    node's children column).
+ *  - `path`: the highlight breadcrumb shaped as `{ key: uid, label }`, so it
+ *    aligns with `expandedPath[level].key === uid` in the node view.
+ *
+ * Stops safely at the last valid segment if the value path does not exist in
+ * the data source.
+ *
+ * @param arr - The selected path. In `multiple` mode the value is an array of
+ *   paths; the first path is used to drive which columns get expanded.
  * @param data - The flattened options data
  * @param options - Optional configuration
- * @returns A tuple of [queue, path] where queue is the column data and path is the selected path info
+ * @returns A tuple of `[queue, path]`
  */
-export declare const changeToView: (arr: Array<string | number>, data: Array<FlattenOption>, options?: {
-    needNext?: boolean | undefined;
+export declare const changeToView: (arr: Array<string | number> | Array<Array<string | number>>, data: Array<FlattenOption>, options?: {
     multiple?: boolean | undefined;
-} | undefined) => (FlattenOption[][] | {
-    id: string | number;
-    text: string;
-}[])[];
+} | undefined) => [FlattenOption[][], Array<{
+    key: string;
+    label: string;
+}>];
 /**
- * Format a path array into a key string
+ * Format a value path into a key string. Alias of `pathToUid` so all path→key
+ * conversions share one collision-safe format.
  * @param val - The path array
- * @returns A string key joined by '-'
  */
 export declare const formatKey: (val: Array<string | number>) => string;
 /**
@@ -37,13 +72,22 @@ export declare const isSamePrefixPath: (prefix: Array<unknown>, target: Array<un
  * Determine if a node is fully selected or half selected (indeterminate)
  * @param value - The selected value paths
  * @param item - The flatten option node to check
+ * @param children - The node's direct flattened children (derive via `getChildren`)
  * @returns A tuple [checkedAll, indeterminate]
  */
-export declare function isHalfChecked(value: Array<Array<string | number>>, item: FlattenOption): boolean[];
+export declare function isHalfChecked(value: Array<Array<string | number>>, item: FlattenOption, children: FlattenOption[]): boolean[];
 /**
- * Flatten a tree structure into an array for easier searching and traversal
+ * Flatten a tree structure into an array for easier searching and traversal.
+ *
+ * The flattened nodes intentionally do NOT carry a `children` field — use
+ * `getChildren(data, uid)` to read a node's children. `uid`/`pid` are built
+ * via `pathToUid` (collision-safe). Includes a depth cap and a cycle guard so
+ * malformed input (very deep or self-referencing trees) cannot overflow the
+ * stack.
+ *
  * @param tree - The tree data to flatten
  * @param fieldNames - Custom field names for label, value, and children
+ * @param maxDepth - Maximum nesting depth (default 100)
  * @returns An array of flattened options with additional metadata
  */
-export declare const flattenOptions: (tree: Array<Record<string, unknown>>, fieldNames: FieldNames) => FlattenOption[];
+export declare const flattenOptions: (tree: Array<Record<string, unknown>>, fieldNames?: FieldNames, maxDepth?: number) => FlattenOption[];