@zidian-primitive/cascader 0.0.0-next-20260204023823

package/README.md

@@ -0,0 +1,436 @@
+# @zidian-base/cascader
+
+A flexible cascader component library built with component composition pattern, providing complete UI and logic for hierarchical selection.
+
+## Features
+
+- 🎯 **Component-Based Architecture**: Modular components for maximum flexibility
+- 🔄 **Flexible Data Sources**: Support both hierarchical and flat data structures
+- 🎨 **Fully Customizable**: Extensive slots for custom rendering
+- ♿ **Accessibility**: Built with accessibility in mind
+- 🔍 **Multiple Selection Modes**: Single and multiple selection support
+- 📦 **TypeScript Support**: Full type safety
+- 🚀 **Performance Optimized**: Efficient state management and rendering
+
+## Installation
+
+```bash
+npm install @zidian-base/cascader
+```
+
+## Quick Start
+
+```tsx
+import React, { useState } from 'react'
+import {
+  CascaderRoot,
+  CascaderPanel,
+  CascaderNode,
+  CascaderPanelHeader,
+  CascaderPanelIndicator,
+  useCascader,
+  type CascaderItem
+} from '@zidian-base/cascader'
+
+const data = [
+  { category: 'Electronics', type: 'Phone', brand: 'iPhone' },
+  { category: 'Electronics', type: 'Phone', brand: 'Samsung' },
+  { category: 'Electronics', type: 'Laptop', brand: 'MacBook' },
+  { category: 'Clothing', type: 'Shirt', brand: 'Nike' },
+]
+
+const handleDataConfig = {
+  levels: ['category', 'type', 'brand']
+}
+
+export default function App() {
+  const cascader = useCascader({
+    data,
+    handleDataConfig,
+    selectOption: {
+      defaultSelected: [],
+      selectType: 'single'
+    }
+  })
+
+  const handleSelect = (nodeIdx: number) => {
+    cascader.handleChangeCheckStatus(nodeIdx)
+  }
+
+  return (
+    <CascaderRoot
+      isSelected={true}
+      selectType="single"
+      onSelectChange={handleSelect}
+    >
+      <CascaderPanel>
+        <CascaderPanelHeader 
+          column={cascader.columns[0]} 
+          showNode={null} 
+        />
+        <CascaderPanelIndicator />
+        
+        {cascader.columns.map((column, level) => (
+          <div key={level} className="cascader-column">
+            {column.map((node) => (
+              <CascaderNode
+                key={node.index}
+                node={node}
+                onSelectChange={() => handleSelect(node.indices)}
+              />
+            ))}
+          </div>
+        ))}
+      </CascaderPanel>
+    </CascaderRoot>
+  )
+}
+```
+
+## API Reference
+
+### Hook
+
+#### useCascader
+
+```ts
+const cascader = useCascader({
+  data: T[],
+  handleDataConfig: FlatDataConfig,
+  selectOption?: SelectOption
+})
+```
+
+**Hook Configuration**
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| data | `T[]` | - | Flat data array |
+| handleDataConfig | `FlatDataConfig` | - | Configuration for converting flat data to hierarchical |
+| selectOption | `SelectOption` | - | Selection configuration |
+
+**Hook Return Values**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| nodes | `CascaderNodeType<T>[]` | All nodes in the cascader |
+| columns | `CascaderItem<T>[][]` | Visible columns based on current selection |
+| showIndices | `number[]` | Indices of currently shown nodes |
+| checkStatusArray | `Uint8Array` | Check status of all nodes |
+| handleShowIndices | `(depth: number, index: number) => void` | Handle column expansion |
+| handleChangeCheckStatus | `(nodeIdx: number) => void` | Handle node selection |
+
+### Components
+
+#### CascaderRoot
+
+The root component that provides cascader context.
+
+```tsx
+<CascaderRoot
+  isSelected={boolean}
+  selectType={'single' | 'multiple'}
+  onSelectChange={(nodeIdx: number) => void}
+  {...divProps}
+>
+  {children}
+</CascaderRoot>
+```
+
+**Props**
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| isSelected | `boolean` | `false` | Whether selection is enabled |
+| selectType | `'single' | 'multiple'` | - | Selection mode |
+| onSelectChange | `(nodeIdx: number) => void` | - | Selection change callback |
+
+#### CascaderPanel
+
+Container for cascader columns and panels.
+
+```tsx
+<CascaderPanel {...divProps}>
+  {children}
+</CascaderPanel>
+```
+
+#### CascaderPanelHeader
+
+Header component for displaying column information.
+
+```tsx
+<CascaderPanelHeader
+  column={CascaderNodeType<any>[]}
+  showNode={CascaderItem<any> | null}
+/>
+```
+
+**Props**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| column | `CascaderNodeType<any>[]` | Current column nodes |
+| showNode | `CascaderItem<any> | null` | Currently shown node |
+
+#### CascaderPanelIndicator
+
+Visual indicator for panel navigation.
+
+```tsx
+<CascaderPanelIndicator />
+```
+
+#### CascaderNode
+
+Individual node component in the cascader.
+
+```tsx
+<CascaderNode
+  node={CascaderItem<any>}
+  onSelectChange={(nodeIdx: number) => void}
+  {...divProps}
+/>
+```
+
+**Props**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| node | `CascaderItem<any>` | Node data |
+| onSelectChange | `(nodeIdx: number) => void` | Selection change callback |
+
+### Types
+
+#### CascaderNodeType
+
+```ts
+interface CascaderNodeType<T = any> {
+  depth: number
+  index: number
+  parentIndex: number
+  range: [number, number]
+  childrenIndices: number[]
+  pathId: string
+  label: string
+  value: string | number
+  raw: T | null
+}
+```
+
+#### CascaderItem
+
+```ts
+interface CascaderItem<T> {
+  indices: number
+  level: number
+  label: string
+  value: string | number
+  originData?: T
+  checkStatus?: CheckStatus
+}
+```
+
+#### FlatDataConfig
+
+```ts
+interface FlatDataConfig {
+  levels: (string | [string, string])[]
+}
+```
+
+#### SelectOption
+
+```ts
+interface SelectOption {
+  defaultSelected: string[]
+  selectType: 'single' | 'multiple'
+}
+```
+
+#### CheckStatus
+
+```ts
+type CheckStatus = 0 | 1 | 2
+// 0: unchecked, 1: partially checked, 2: fully checked
+```
+
+## Usage Examples
+
+### Multiple Selection Mode
+
+```tsx
+const cascader = useCascader({
+  data,
+  handleDataConfig,
+  selectOption: {
+    defaultSelected: [],
+    selectType: 'multiple'
+  }
+})
+
+<CascaderRoot
+  isSelected={true}
+  selectType="multiple"
+  onSelectChange={cascader.handleChangeCheckStatus}
+>
+  {/* Components */}
+</CascaderRoot>
+```
+
+### Custom Node Rendering
+
+```tsx
+const CustomNode = ({ node, onSelectChange }) => {
+  return (
+    <CascaderNode
+      node={node}
+      onSelectChange={onSelectChange}
+      className="custom-node"
+    >
+      <div className="node-content">
+        <span className="node-label">{node.label}</span>
+        {node.checkStatus === 2 && <span>✓</span>}
+      </div>
+    </CascaderNode>
+  )
+}
+```
+
+### Custom Header
+
+```tsx
+const CustomHeader = ({ column, showNode }) => {
+  return (
+    <CascaderPanelHeader column={column} showNode={showNode}>
+      <div className="custom-header">
+        {showNode ? `Selected: ${showNode.label}` : 'Please select'}
+      </div>
+    </CascaderPanelHeader>
+  )
+}
+```
+
+### Async Data Loading
+
+```tsx
+const [data, setData] = useState([])
+
+useEffect(() => {
+  fetchData().then(setData)
+}, [])
+
+const cascader = useCascader({
+  data,
+  handleDataConfig,
+  selectOption: {
+    defaultSelected: [],
+    selectType: 'single'
+  }
+})
+```
+
+### Controlled Selection
+
+```tsx
+const [selectedValues, setSelectedValues] = useState([])
+
+const handleSelect = useCallback((nodeIdx: number) => {
+  const node = cascader.nodes[nodeIdx]
+  const newValue = cascader.selectOption.selectType === 'single' 
+    ? [node.value]
+    : [...selectedValues, node.value]
+  
+  setSelectedValues(newValue)
+  cascader.handleChangeCheckStatus(nodeIdx)
+}, [cascader, selectedValues])
+```
+
+## Advanced Patterns
+
+### Search Functionality
+
+```tsx
+const [searchTerm, setSearchTerm] = useState('')
+const [filteredData, setFilteredData] = useState(data)
+
+useEffect(() => {
+  const filtered = data.filter(item =>
+    Object.values(item).some(value =>
+      String(value).toLowerCase().includes(searchTerm.toLowerCase())
+    )
+  )
+  setFilteredData(filtered)
+}, [searchTerm])
+
+const cascader = useCascader({
+  data: filteredData,
+  handleDataConfig
+})
+```
+
+### Custom Animation
+
+```tsx
+import { motion } from 'framer-motion'
+
+const AnimatedNode = ({ node, onSelectChange }) => {
+  return (
+    <motion.div
+      initial={{ opacity: 0, y: -10 }}
+      animate={{ opacity: 1, y: 0 }}
+      exit={{ opacity: 0, y: -10 }}
+    >
+      <CascaderNode node={node} onSelectChange={onSelectChange} />
+    </motion.div>
+  )
+}
+```
+
+## Data Structure Examples
+
+### Hierarchical Data (Converted from Flat)
+
+```tsx
+const flatData = [
+  { level1: 'Electronics', level2: 'Phones', level3: 'iPhone' },
+  { level1: 'Electronics', level2: 'Phones', level3: 'Samsung' },
+  { level1: 'Electronics', level2: 'Laptops', level3: 'MacBook' },
+]
+
+const config = {
+  levels: ['level1', 'level2', 'level3']
+}
+```
+
+### Complex Field Mapping
+
+```tsx
+const complexData = [
+  { 
+    category: { name: 'Electronics', id: 1 }, 
+    product: { name: 'iPhone', type: 'Phone' },
+    brand: 'Apple'
+  }
+]
+
+const complexConfig = {
+  levels: [
+    ['category', 'name'],  // Use category.name as label
+    ['product', 'name'],   // Use product.name as label  
+    'brand'                // Use brand directly
+  ]
+}
+```
+
+## Best Practices
+
+1. **Performance**: Use `useMemo` for data transformations and filtering
+2. **Accessibility**: Ensure keyboard navigation and screen reader support
+3. **State Management**: Keep selection state in parent component for controlled behavior
+4. **Customization**: Use slots for custom rendering while maintaining core functionality
+5. **Data Structure**: Keep data flat for better performance and easier manipulation
+
+## License
+
+MIT

package/esm/components/node/CascaderNode.js

@@ -0,0 +1,41 @@
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+import { useContext } from 'react';
+import { CascaderContext, CascaderPanelContext } from '../../context/index.js';
+
+const CascaderNode = (props) => {
+  const {
+    node,
+    isLeaf,
+    onClick,
+    onTrigger,
+    render,
+    ...elementProps
+  } = props;
+  const { onSelectChange } = useContext(CascaderContext);
+  const { showIndicator, registerNode } = useContext(CascaderPanelContext);
+  const handleClick = (event) => {
+    if (isLeaf) {
+      if (onClick) onClick(node);
+    } else {
+      if (onTrigger) onTrigger(node.level, node.indices);
+    }
+  };
+  return /* @__PURE__ */ jsx("div", { ref: showIndicator ? (el) => registerNode(node.indices, el) : void 0, onClick: handleClick, ...elementProps, children: render ? render({ node, onSelectChange }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx("span", { style: { flex: 1 }, children: node.label }),
+    !isLeaf && /* @__PURE__ */ jsx(
+      "svg",
+      {
+        xmlns: "http://www.w3.org/2000/svg",
+        width: "18",
+        height: "18",
+        viewBox: "0 0 24 24",
+        fill: "none",
+        stroke: "currentColor",
+        children: /* @__PURE__ */ jsx("path", { d: "m9 18 6-6-6-6" })
+      }
+    )
+  ] }) });
+};
+CascaderNode.displayName = "CascaderNode";
+
+export { CascaderNode };

package/esm/components/node/CascaderNodeCheck.js

@@ -0,0 +1,7 @@
+import { jsx } from 'react/jsx-runtime';
+
+const CascaderNodeCheck = () => {
+  return /* @__PURE__ */ jsx("div", {});
+};
+
+export { CascaderNodeCheck };

package/esm/components/panel/CascaderPanel.js

@@ -0,0 +1,40 @@
+import { jsx } from 'react/jsx-runtime';
+import { forwardRef, useRef, useState, useCallback, useLayoutEffect } from 'react';
+import { CascaderPanelContext } from '../../context/index.js';
+
+const CascaderPanel = forwardRef((props, ref) => {
+  const {
+    depth,
+    children,
+    showIndicator = false,
+    activeIndices,
+    ...elementProps
+  } = props;
+  const nodeRefs = useRef(/* @__PURE__ */ new Map());
+  const [indicatorStyle, setIndicatorStyle] = useState();
+  const registerNode = useCallback((index, el) => {
+    if (el) nodeRefs.current.set(index, el);
+    else nodeRefs.current.delete(index);
+  }, []);
+  useLayoutEffect(() => {
+    if (activeIndices === void 0) return;
+    const activeEl = nodeRefs.current.get(activeIndices);
+    if (activeEl) {
+      const measure = () => {
+        setIndicatorStyle({
+          ["--indicator-offset-top"]: `${activeEl.offsetTop}px`,
+          ["--indicator-height"]: `${activeEl.offsetHeight}px`,
+          transform: `translateY(var(--indicator-offset-top))`,
+          height: `${activeEl.offsetHeight}px`
+        });
+      };
+      measure();
+      const resizeObserver = new ResizeObserver(measure);
+      resizeObserver.observe(activeEl);
+    }
+  }, [activeIndices]);
+  return /* @__PURE__ */ jsx(CascaderPanelContext.Provider, { value: { showIndicator, activeIndices, registerNode, indicatorStyle }, children: /* @__PURE__ */ jsx("div", { ref, "data-depth": depth, "data-active-indices": activeIndices, ...elementProps, children }) });
+});
+CascaderPanel.displayName = "CascaderPanel";
+
+export { CascaderPanel };

package/esm/components/panel/CascaderPanelHeader.js

@@ -0,0 +1,20 @@
+import { jsxs, jsx } from 'react/jsx-runtime';
+import { useContext } from 'react';
+import { CascaderContext } from '../../context/index.js';
+
+const CascaderPanelHeader = (props) => {
+  const {
+    column,
+    showNode,
+    render,
+    ...elementProps
+  } = props;
+  const { selectType } = useContext(CascaderContext);
+  if (render) render({ column, showNode });
+  else return /* @__PURE__ */ jsxs("div", { ...elementProps, children: [
+    /* @__PURE__ */ jsx("span", { children: showNode?.level }),
+    /* @__PURE__ */ jsx("span", { children: column.length })
+  ] });
+};
+
+export { CascaderPanelHeader };

package/esm/components/panel/CascaderPanelIndicator.js

@@ -0,0 +1,17 @@
+import { jsx } from 'react/jsx-runtime';
+import { useContext } from 'react';
+import { CascaderPanelContext } from '../../context/index.js';
+
+const CascaderPanelIndicator = (props) => {
+  const {
+    render,
+    ...elementProps
+  } = props;
+  const { indicatorStyle, activeIndices } = useContext(CascaderPanelContext);
+  if (render) return render();
+  if (activeIndices === void 0) return null;
+  return /* @__PURE__ */ jsx("div", { style: indicatorStyle, ...elementProps });
+};
+CascaderPanelIndicator.displayName = "CascaderPanelIndicator";
+
+export { CascaderPanelIndicator };

package/esm/components/root/CascaderRoot.js

@@ -0,0 +1,21 @@
+import { jsx } from 'react/jsx-runtime';
+import { forwardRef } from 'react';
+import { CascaderContext } from '../../context/index.js';
+
+const CascaderRoot = forwardRef((props, ref) => {
+  const {
+    isSelected = false,
+    selectType,
+    onSelectChange,
+    children,
+    ...elementProps
+  } = props;
+  return /* @__PURE__ */ jsx(CascaderContext.Provider, { value: {
+    isSelected,
+    selectType,
+    onSelectChange
+  }, children: /* @__PURE__ */ jsx("div", { ref, ...elementProps, children }) });
+});
+CascaderRoot.displayName = "CascaderRoot";
+
+export { CascaderRoot };

package/esm/context/index.js

@@ -0,0 +1,15 @@
+import { createContext } from 'react';
+
+const BLANK_FUNCTION = () => {
+};
+const CascaderContext = createContext({
+  isSelected: false,
+  selectType: "single",
+  onSelectChange: void 0
+});
+const CascaderPanelContext = createContext({
+  showIndicator: false,
+  registerNode: BLANK_FUNCTION
+});
+
+export { CascaderContext, CascaderPanelContext };

package/esm/hooks/useCascader.js

@@ -0,0 +1,61 @@
+import { useMemo, useState } from 'react';
+import { buildCascaderEngine, getDefaultIndices, getCascadeColumns, getShowIndices } from '../utils/data.js';
+import { setMultipleNodeStatus, setNodeCheckStatus } from '../utils/logic.js';
+
+function useCascader(options) {
+  const { data, handleDataConfig, selectOption } = options;
+  const sortedData = useMemo(() => {
+    return data.sort((a, b) => {
+      for (const field of handleDataConfig.levels) {
+        const f = Array.isArray(field) ? field[0] : field;
+        if (a[f] !== b[f]) return String(a[f]).localeCompare(String(b[f]));
+      }
+      return 0;
+    });
+  }, [data, handleDataConfig]);
+  const defaultNodes = useMemo(() => {
+    return buildCascaderEngine(sortedData, handleDataConfig);
+  }, [sortedData, handleDataConfig]);
+  const defaultStatusArray = useMemo(() => {
+    const statusArray = new Uint8Array(defaultNodes.length);
+    if (selectOption?.defaultSelected) {
+      const defaultIndices = defaultNodes.filter(
+        (node) => selectOption.defaultSelected.find(
+          (selected) => node.raw?.value === selected
+        )
+      ).map((node) => node.index);
+      return setMultipleNodeStatus(defaultNodes, statusArray, defaultIndices, 1);
+    }
+    return statusArray;
+  }, [defaultNodes, selectOption?.defaultSelected]);
+  useMemo(() => Boolean(selectOption), [selectOption]);
+  const [checkStatusArray, setCheckStatusArray] = useState(defaultStatusArray);
+  const [showIndices, setShowIndices] = useState(getDefaultIndices(defaultNodes));
+  const columns = useMemo(() => getCascadeColumns(defaultNodes, showIndices), [defaultNodes, showIndices]);
+  const handleShowIndices = (depth, index) => {
+    setShowIndices(getShowIndices(
+      defaultNodes,
+      {
+        oldShowIndices: showIndices,
+        actionIndices: {
+          depth,
+          nodeIdx: index
+        }
+      }
+    ));
+  };
+  const handleChangeCheckStatus = (nodeIdx) => {
+    const newStatusArray = setNodeCheckStatus(defaultNodes, checkStatusArray, nodeIdx);
+    setCheckStatusArray(newStatusArray);
+  };
+  return {
+    nodes: defaultNodes,
+    columns,
+    showIndices,
+    checkStatusArray,
+    handleShowIndices,
+    handleChangeCheckStatus
+  };
+}
+
+export { useCascader };

package/esm/index.js

@@ -0,0 +1,9 @@
+export { CascaderRoot } from './components/root/CascaderRoot.js';
+export { CascaderNode } from './components/node/CascaderNode.js';
+export { CascaderNodeCheck } from './components/node/CascaderNodeCheck.js';
+export { CascaderPanel } from './components/panel/CascaderPanel.js';
+export { CascaderPanelHeader } from './components/panel/CascaderPanelHeader.js';
+export { CascaderPanelIndicator } from './components/panel/CascaderPanelIndicator.js';
+export { useCascader } from './hooks/useCascader.js';
+export { buildCascaderEngine, getCascadeColumns, getDefaultIndices, getShowIndices } from './utils/data.js';
+export { setMultipleNodeStatus, setNodeCheckStatus } from './utils/logic.js';

package/esm/utils/data.js

@@ -0,0 +1,102 @@
+function createCascaderNode(option) {
+  const { depth, currentIndex, parentIndex, row, label, value, pathId } = option;
+  return {
+    depth,
+    index: currentIndex,
+    parentIndex,
+    range: [currentIndex, currentIndex],
+    childrenIndices: [],
+    pathId,
+    label,
+    value,
+    raw: row
+  };
+}
+function buildCascaderEngine(data, config) {
+  let currentIndex = 0;
+  const currentConfig = config;
+  const nodes = [];
+  const nodeMap = /* @__PURE__ */ new Map();
+  const levelConfigs = currentConfig.levels;
+  data.forEach((item, itemIndex) => {
+    let parentIndex = -1;
+    let currentPathId = "";
+    for (let levelIndex = 0; levelIndex < levelConfigs.length; levelIndex++) {
+      const field = levelConfigs[levelIndex];
+      let labelField, valueField = "";
+      if (Array.isArray(field)) {
+        labelField = field[0];
+        valueField = field[1];
+      } else {
+        labelField = valueField = field;
+      }
+      const label = item[labelField];
+      const value = item[valueField];
+      if (label === void 0 || label === null) break;
+      const labelStr = typeof item[labelField] === "string" ? item[labelField] : `${itemIndex}-${levelIndex}`;
+      currentPathId = levelIndex == 0 ? labelStr : `${currentPathId}
${labelStr}`;
+      let nodeIdx = nodeMap.get(currentPathId);
+      if (nodeIdx === void 0) {
+        nodeIdx = currentIndex++;
+        nodeMap.set(currentPathId, nodeIdx);
+        levelIndex === levelConfigs.length - 1;
+        nodes[nodeIdx] = createCascaderNode({
+          parentIndex,
+          currentIndex: nodeIdx,
+          pathId: currentPathId,
+          depth: levelIndex,
+          label,
+          value,
+          row: item
+        });
+        if (parentIndex !== -1) {
+          nodes[parentIndex].childrenIndices.push(nodeIdx);
+        }
+      }
+      parentIndex = nodeIdx;
+    }
+  });
+  for (let i = nodes.length - 1; i >= 0; i--) {
+    const node = nodes[i];
+    if (node.childrenIndices.length > 0) {
+      const lastChildIdx = node.childrenIndices[node.childrenIndices.length - 1];
+      node.range[1] = nodes[lastChildIdx].range[1];
+    }
+  }
+  return nodes;
+}
+function getCascadeColumns(nodes, showIndices) {
+  const columns = [];
+  const rootColumn = nodes.filter((node) => node.parentIndex === -1);
+  columns.push(rootColumn);
+  showIndices.forEach((selectedIndex) => {
+    const parentNode = nodes[selectedIndex];
+    if (parentNode && parentNode.childrenIndices.length > 0) {
+      const nextColumn = parentNode.childrenIndices.map((idx) => nodes[idx]);
+      columns.push(nextColumn);
+    }
+  });
+  return columns;
+}
+function getShowIndices(nodes, option) {
+  const { oldShowIndices, actionIndices } = option;
+  let targetPath = [];
+  const { depth, nodeIdx } = actionIndices;
+  let currentNode = nodes[nodeIdx];
+  while (currentNode.childrenIndices.length > 0) {
+    targetPath.push(currentNode.index);
+    currentNode = nodes[currentNode.childrenIndices[0]];
+  }
+  return oldShowIndices.slice(0, depth).concat(targetPath);
+}
+function getDefaultIndices(nodes) {
+  let defaultIndices = [];
+  let currentNode = nodes[0];
+  while (currentNode.childrenIndices.length > 0) {
+    defaultIndices.push(currentNode.index);
+    currentNode = nodes[currentNode.childrenIndices[0]];
+  }
+  return defaultIndices;
+}
+
+export { buildCascaderEngine, getCascadeColumns, getDefaultIndices, getShowIndices };

package/esm/utils/logic.js

@@ -0,0 +1,79 @@
+const CHECK_NONE = 0;
+const CHECK_ALL = 1;
+const CHECK_INDETERMINATE = 2;
+function propagateToChildren(statusArray, range, status) {
+  const [start, end] = range;
+  statusArray.fill(status, start, end + 1);
+}
+function propagateToParents(nodes, statusArray, childIndex) {
+  const childNode = nodes[childIndex];
+  if (!childNode || childNode.parentIndex === -1) return;
+  const parentIdx = childNode.parentIndex;
+  const parentNode = nodes[parentIdx];
+  const children = parentNode.childrenIndices;
+  let checkedCount = 0;
+  let hasIndeterminate = false;
+  for (const idx of children) {
+    const s = statusArray[idx];
+    if (s === CHECK_ALL) checkedCount++;
+    else if (s === CHECK_INDETERMINATE) hasIndeterminate = true;
+  }
+  let parentStatus = CHECK_NONE;
+  if (checkedCount === children.length) {
+    parentStatus = CHECK_ALL;
+  } else if (checkedCount > 0 || hasIndeterminate) {
+    parentStatus = CHECK_INDETERMINATE;
+  }
+  if (statusArray[parentIdx] !== parentStatus) {
+    statusArray[parentIdx] = parentStatus;
+    propagateToParents(nodes, statusArray, parentIdx);
+  }
+}
+function setNodeCheckStatus(nodes, currentStatusArray, nodeIndex) {
+  const nextStatus = new Uint8Array(currentStatusArray);
+  const targetNode = nodes[nodeIndex];
+  const targetValue = nextStatus[nodeIndex] === CHECK_ALL ? CHECK_NONE : nextStatus[nodeIndex] === CHECK_INDETERMINATE ? CHECK_NONE : CHECK_ALL;
+  propagateToChildren(nextStatus, targetNode.range, targetValue);
+  propagateToParents(nodes, nextStatus, nodeIndex);
+  return nextStatus;
+}
+function syncUpPath(nodes, statusArray, parentIdx) {
+  let currIdx = parentIdx;
+  while (currIdx !== -1) {
+    const node = nodes[currIdx];
+    const children = node.childrenIndices;
+    let checkedCount = 0;
+    let hasIndeterminate = false;
+    for (const childIdx of children) {
+      const s = statusArray[childIdx];
+      if (s === 1) checkedCount++;
+      else if (s === 2) hasIndeterminate = true;
+    }
+    let nextS = 0;
+    if (checkedCount === children.length) nextS = 1;
+    else if (checkedCount > 0 || hasIndeterminate) nextS = 2;
+    if (statusArray[currIdx] === nextS) break;
+    statusArray[currIdx] = nextS;
+    currIdx = node.parentIndex;
+  }
+}
+function setMultipleNodeStatus(nodes, currentStatusArray, indices, targetStatus) {
+  const nextStatus = new Uint8Array(currentStatusArray);
+  const parentsToSync = /* @__PURE__ */ new Set();
+  indices.forEach((index) => {
+    const node = nodes[index];
+    if (!node) return;
+    const [start, end] = node.range;
+    nextStatus.fill(targetStatus, start, end + 1);
+    if (node.parentIndex !== -1) {
+      parentsToSync.add(node.parentIndex);
+    }
+  });
+  const sortedParents = Array.from(parentsToSync).sort((a, b) => b - a);
+  sortedParents.forEach((parentIdx) => {
+    syncUpPath(nodes, nextStatus, parentIdx);
+  });
+  return nextStatus;
+}
+
+export { setMultipleNodeStatus, setNodeCheckStatus };

package/lib/components/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./root/CascaderRoot";
+export * from "./node/CascaderNode";
+export * from "./node/CascaderNodeCheck";
+export * from "./panel/CascaderPanel";
+export * from "./panel/CascaderPanelHeader";
+export * from "./panel/CascaderPanelIndicator";

package/lib/components/node/CascaderNode.d.ts

@@ -0,0 +1,10 @@
+import { ComponentProps } from "react";
+import { CascaderItem, NodeSlotType } from "../../types";
+export interface CascaderNodeProps extends Omit<ComponentProps<'div'>, "onClick"> {
+    node: CascaderItem<any>;
+    isLeaf: boolean;
+    onClick?: (node: CascaderItem<any>) => void;
+    onTrigger?: (depth: number, nodeIdx: number) => void;
+    render?: NodeSlotType;
+}
+export declare const CascaderNode: React.FC<CascaderNodeProps>;

package/lib/components/node/CascaderNodeCheck.d.ts

@@ -0,0 +1 @@
+export declare const CascaderNodeCheck: () => import("react/jsx-runtime").JSX.Element;

package/lib/components/panel/CascaderPanel.d.ts

@@ -0,0 +1,7 @@
+import { ComponentProps } from 'react';
+export interface CascaderPanelProps extends ComponentProps<'div'> {
+    depth: number;
+    showIndicator?: boolean;
+    activeIndices?: number;
+}
+export declare const CascaderPanel: import("react").ForwardRefExoticComponent<Omit<CascaderPanelProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;

package/lib/components/panel/CascaderPanelHeader.d.ts

@@ -0,0 +1,8 @@
+import { ComponentProps, FC } from "react";
+import { CascaderItem, CascaderNodeType, PanelHeaderSlot } from "../../types";
+export interface CascaderPanelHeaderProps extends ComponentProps<'div'> {
+    column: CascaderNodeType<any>[];
+    showNode: CascaderItem<any> | null;
+    render?: PanelHeaderSlot;
+}
+export declare const CascaderPanelHeader: FC<CascaderPanelHeaderProps>;

package/lib/components/panel/CascaderPanelIndicator.d.ts

@@ -0,0 +1,6 @@
+import { ComponentProps, FC } from "react";
+import { PanelIndicatorSlot } from "../../types";
+export interface CascaderPanelIndicatorProps extends ComponentProps<'div'> {
+    render?: PanelIndicatorSlot;
+}
+export declare const CascaderPanelIndicator: FC<CascaderPanelIndicatorProps>;

package/lib/components/root/CascaderRoot.d.ts

@@ -0,0 +1,7 @@
+import { ComponentProps } from "react";
+export interface CascaderRootProps extends ComponentProps<'div'> {
+    isSelected?: boolean;
+    selectType?: "single" | "multiple";
+    onSelectChange?: (nodeIdx: number) => void;
+}
+export declare const CascaderRoot: import("react").ForwardRefExoticComponent<Omit<CascaderRootProps, "ref"> & import("react").RefAttributes<unknown>>;

package/lib/context/index.d.ts

@@ -0,0 +1,12 @@
+import { CSSProperties } from "react";
+export declare const CascaderContext: import("react").Context<{
+    isSelected: boolean;
+    selectType: "single" | "multiple" | undefined;
+    onSelectChange: ((nodeIdx: number) => void) | undefined;
+}>;
+export declare const CascaderPanelContext: import("react").Context<{
+    showIndicator: boolean;
+    indicatorStyle?: CSSProperties;
+    activeIndices?: number;
+    registerNode: (index: number, el: HTMLElement | null) => void;
+}>;

package/lib/hooks/useCascader.d.ts

@@ -0,0 +1,14 @@
+import { CascaderNodeType, SelectOption, FlatDataConfig } from "../types";
+export type CascaderHookOption<T> = {
+    data: T[];
+    handleDataConfig: FlatDataConfig;
+    selectOption?: SelectOption;
+};
+export declare function useCascader<T extends Record<string, any>>(options: CascaderHookOption<T>): {
+    nodes: CascaderNodeType<T>[];
+    columns: CascaderNodeType<T>[][];
+    showIndices: number[];
+    checkStatusArray: Uint8Array<ArrayBufferLike>;
+    handleShowIndices: (depth: number, index: number) => void;
+    handleChangeCheckStatus: (nodeIdx: number) => void;
+};

package/lib/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./components";
+export * from "./hooks/useCascader";
+export * from "./utils/index";
+export * from "./types";

package/lib/types/index.d.ts

@@ -0,0 +1,59 @@
+import { ReactNode } from "react";
+export type CheckStatus = 0 | 1 | 2;
+/**============================================
+ **               Data
+ *=============================================**/
+export interface CascaderNodeType<T = any> {
+    depth: number;
+    index: number;
+    parentIndex: number;
+    range: [number, number];
+    childrenIndices: number[];
+    pathId: string;
+    label: string;
+    value: string | number;
+    raw: T | null;
+}
+export interface CascaderItem<T> {
+    indices: number;
+    level: number;
+    label: string;
+    value: string | number;
+    originData?: T;
+    checkStatus?: CheckStatus;
+}
+/**============================================
+ **               Utils
+ *=============================================**/
+export type FlatDataConfig = {
+    levels: (string | [string, string])[];
+};
+export type GetShowIndicesOption = {
+    oldShowIndices: number[];
+    actionIndices: {
+        depth: number;
+        nodeIdx: number;
+    };
+};
+export type GetCascaderColumnsOption = {
+    checkStatusArray?: Uint8Array<ArrayBufferLike>;
+};
+/**============================================
+ **               Others
+ *=============================================**/
+export type SelectOption = {
+    defaultSelected: string[];
+    selectType: "single" | "multiple";
+};
+/**============================================
+ **               Slot
+ *=============================================**/
+export type PanelHeaderSlot = (props: {
+    column: CascaderNodeType<any>[];
+    showNode: CascaderItem<any> | null;
+}) => ReactNode;
+export type PanelIndicatorSlot = (props?: any) => ReactNode;
+export type NodeSlotType = (props: {
+    node: CascaderItem<any>;
+    onSelectChange?: (nodeIdx: number) => void;
+}) => ReactNode;

package/lib/utils/data.d.ts

@@ -0,0 +1,5 @@
+import { CascaderNodeType, FlatDataConfig, GetShowIndicesOption } from '../types/index.js';
+export declare function buildCascaderEngine<T extends Record<string, any>>(data: T[], config: FlatDataConfig): CascaderNodeType<T>[];
+export declare function getCascadeColumns<T>(nodes: CascaderNodeType<T>[], showIndices: number[]): CascaderNodeType<T>[][];
+export declare function getShowIndices<T>(nodes: CascaderNodeType<T>[], option: GetShowIndicesOption): number[];
+export declare function getDefaultIndices<T>(nodes: CascaderNodeType<T>[]): number[];

package/lib/utils/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./data";
+export * from "./logic";

package/lib/utils/logic.d.ts

@@ -0,0 +1,3 @@
+import { CascaderNodeType } from "src/types";
+export declare function setNodeCheckStatus<T>(nodes: CascaderNodeType<T>[], currentStatusArray: Uint8Array, nodeIndex: number): Uint8Array;
+export declare function setMultipleNodeStatus<T>(nodes: CascaderNodeType<T>[], currentStatusArray: Uint8Array, indices: number[], targetStatus: number): Uint8Array;

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@zidian-primitive/cascader",
+  "version": "0.0.0-next-20260204023823",
+  "main": "./src/index.ts",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zidcn/component-lib.git",
+    "directory": "packages/@zidian-primitive/cascader"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./esm/index.js",
+      "default": "./esm/index.js"
+    }
+  },
+  "files": [
+    "esm",
+    "lib",
+    "README.md"
+  ],
+  "author": "GWR",
+  "peerDependencies": {
+    "react": "^18.x || ^19.x",
+    "react-dom": "^18.x || ^19.x"
+  },
+  "devDependencies": {
+    "react": "19.0.0",
+    "react-dom": "19.0.0"
+  }
+}