react-extjs 0.0.1

package/src/components/ColorPalette.tsx

@@ -0,0 +1,126 @@
+import { useState, useRef, useEffect, forwardRef, useImperativeHandle } from 'react';
+
+export interface ColorPaletteHandle {
+  /** 整体替换调色板颜色数组（6 位 hex，可带 #） */
+  setColors: (colors: string[]) => void;
+  /** 追加/插入一个颜色（index 省略则追加到末尾） */
+  addColor: (hex: string, index?: number) => void;
+  /** 删除指定颜色值（6 位 hex，可带 #） */
+  removeColor: (hex: string) => void;
+  /** 取当前颜色数组克隆 */
+  getColors: () => string[];
+  /** 选中指定颜色（等价 Ext select） */
+  select: (color: string) => void;
+  /** 取当前选中色（大写 6 位 hex，无选中返回 null） */
+  getSelected: () => string | null;
+}
+
+// Ext.ColorPalette 默认 40 色调色板，顺序与 Ext 源码 colors 数组完全一致，
+// 以保证 golden 与 React 的 40 个 .color-XXXXXX 节点一一对应、像素一致。
+export const COLORS = [
+  '000000', '993300', '333300', '003300', '003366', '000080', '333399', '333333',
+  '800000', 'FF6600', '808000', '008000', '008080', '0000FF', '666699', '808080',
+  'FF0000', 'FF9900', '99CC00', '339966', '33CCCC', '3366FF', '800080', '969696',
+  'FF00FF', 'FFCC00', 'FFFF00', '00FF00', '00FFFF', '00CCFF', '993366', 'C0C0C0',
+  'FF99CC', 'FFCC99', 'FFFF99', 'CCFFCC', 'CCFFFF', '99CCFF', 'CC99FF', 'FFFFFF',
+];
+
+export interface ColorPaletteProps {
+  /** 初始选中色（6 位 hex，可带或不带 #），默认无选中 */
+  value?: string;
+  /** 调色板颜色数组（6 位 hex，可带 #）；省略则用 Ext 默认 42 色 */
+  colors?: string[];
+  /** 选中回调，参数为大写 6 位 hex（不带 #） */
+  onSelect?: (color: string) => void;
+}
+
+// 保真映射（来源 Ext.ColorPalette.onRender 的 XTemplate）：
+//   <tpl for="."><a href="#" class="color-{.}" hidefocus="on">
+//     <em><span style="background:#{.}" unselectable="on">&#160;</span></em></a></tpl>
+// - 根 div class = 'x-color-palette'（itemCls，无额外 baseCls）。
+// - 每色一个 <a class="color-{HEX}">，内部 <em><span style="background:#{HEX}">。
+// - 选中：afterRender 调 select(value)，给对应 <a> 追加 'x-color-palette-sel'。
+//   视觉由 CSS 驱动（a.x-color-palette-sel 设 border-color:#8bb8f3; background:#deecfd），无需额外 DOM。
+// - 全部样式来自 ext-all.css（11 条 .x-color-palette* 规则），零新增 CSS 契约破坏。
+const norm = (v?: string) => (v || '').replace('#', '').toUpperCase();
+
+export const ColorPalette = forwardRef<ColorPaletteHandle, ColorPaletteProps>(
+  ({ value, colors, onSelect }, ref) => {
+  // 单源数组法：dynColors 为唯一真相，句柄运行时改写；useEffect([colors]) 同步 prop 变化。
+  const [dynColors, setDynColors] = useState<string[]>(() => colors ?? COLORS);
+  const colorsRef = useRef<string[]>(dynColors);
+  const [sel, setSel] = useState<string | null>(norm(value) || null);
+  const selRef = useRef<string | null>(sel);
+  useEffect(() => {
+    colorsRef.current = dynColors;
+  }, [dynColors]);
+  useEffect(() => {
+    selRef.current = sel;
+  }, [sel]);
+  useEffect(() => {
+    if (colors) setDynColors(colors);
+  }, [colors]);
+  useEffect(() => {
+    if (value !== undefined) setSel(norm(value) || null);
+  }, [value]);
+
+  useImperativeHandle(
+    ref,
+    (): ColorPaletteHandle => ({
+      setColors: (next) => setDynColors([...next]),
+      addColor: (hex, index) => {
+        setDynColors((prev) => {
+          const next = [...prev];
+          if (index == null || index >= next.length) next.push(hex);
+          else next.splice(index, 0, hex);
+          return next;
+        });
+      },
+      removeColor: (hex) => {
+        const up = norm(hex);
+        setDynColors((prev) => prev.filter((c) => norm(c) !== up));
+      },
+      getColors: () => colorsRef.current.map((c) => c),
+      select: (color) => {
+        const up = norm(color);
+        setSel(up);
+        onSelect?.(up);
+        selRef.current = up;
+      },
+      getSelected: () => selRef.current,
+    }),
+    [onSelect],
+  );
+
+  const select = (hex: string) => {
+    const up = hex.toUpperCase();
+    setSel(up);
+    onSelect?.(up);
+  };
+
+  return (
+    <div className="x-color-palette">
+      {dynColors.map((c) => (
+        <a
+          key={c}
+          className={['color-' + c, sel === c.toUpperCase() ? 'x-color-palette-sel' : '']
+            .filter(Boolean)
+            .join(' ')}
+          href="#"
+          onClick={(e) => {
+            e.preventDefault();
+            select(c);
+          }}
+        >
+          <em>
+            <span style={{ background: `#${c}` }} unselectable="on">
+              {' '}
+            </span>
+          </em>
+        </a>
+      ))}
+    </div>
+  );
+});
+
+ColorPalette.displayName = 'ColorPalette';

package/src/components/ColumnLayout.tsx

@@ -0,0 +1,183 @@
+import {
+  useLayoutEffect,
+  useRef,
+  useState,
+  useMemo,
+  type FC,
+  type CSSProperties,
+  type ReactNode,
+} from 'react';
+import { Panel } from './Panel';
+
+export interface ColumnItem {
+  /** 列标题（渲染 x-panel-header） */
+  title?: string;
+  /** 列主体内容（纯文本/HTML 字符串）；也可用 children 渲染任意 React 节点 */
+  html?: string;
+  children?: ReactNode;
+  /** 固定列宽（px）。与 columnWidth 二选一；给定 width 即不被列宽算法拉伸。 */
+  width?: number;
+  /** 比例列宽（0~1）。多个 columnWidth 按各自比例分配“剩余可用宽”（总宽 − 所有固定列宽）。 */
+  columnWidth?: number;
+  /** 列外边距简写 "t r b l"（同 CSS）。影响列宽分配与渲染。默认 0。 */
+  margins?: string;
+  /** 透传到 x-panel-body 的 inline style */
+  bodyStyle?: CSSProperties;
+  /** 透传到列根元素的附加 class（追加在 .x-column 之后） */
+  cls?: string;
+  /** 透传到列根元素的内联样式（裸列 / 覆盖视觉用） */
+  columnStyle?: CSSProperties;
+  /** 透传到列根元素的 data-id（供拖拽等场景定位列） */
+  dataId?: string;
+  /** 裸列渲染内容（供 Portal 等无需 Panel 包装的场景）。提供 node 时组件只算宽 + float，
+   *  不再包 .x-panel；视觉完全由调用方在 node 内提供（保持中性 / 借原生类名，不硬编码主题色）。 */
+  node?: ReactNode;
+}
+
+export interface ColumnLayoutProps {
+  /** 容器总宽（px），对齐 Ext.Container width。不传或为 0 时自动测量内容区宽（响应式）。 */
+  width?: number;
+  items: ColumnItem[];
+  /** 数据测试 id，挂在根 .x-column-layout-ct 上 */
+  testId?: string;
+  style?: CSSProperties;
+  className?: string;
+  /** 子项默认外边距简写。默认 '0'。 */
+  defaultMargins?: string;
+}
+
+type Margins = { top: number; right: number; bottom: number; left: number };
+
+const parseMargins = (v?: string): Margins => {
+  const p = (v || '0').trim().split(/\s+/).map(Number);
+  const top = p[0] ?? 0;
+  const right = p[1] != null ? p[1] : p[0] ?? 0;
+  const bottom = p[2] != null ? p[2] : p[0] ?? 0;
+  const left = p[3] != null ? p[3] : p[1] != null ? p[1] : p[0] ?? 0;
+  return { top, right, bottom, left };
+};
+
+/**
+ * 复刻 Ext.layout.ColumnLayout（Ext 3.2.1）。
+ *
+ * DOM 对齐 ColumnLayout.js 真值：
+ *  - 容器根 .x-column-layout-ct；
+ *  - renderAll 创建 .x-column-inner（宽=容器宽）；
+ *  - 每个子面板元素追加 extraCls='x-column'（float:left，见 ext-all.css:4757）；
+ *    内联 display:block + width（Ext setSize 设宽）。
+ *
+ * 宽分配算法逐行移植 onLayout（ext-all-debug.js:12637）：
+ *  - 先遍历非 columnWidth 项：pw -= (width + 左右 margin)；
+ *  - 再遍历 columnWidth 项：width = floor(columnWidth * pw) - 左右 margin。
+ *
+ * 铁律对齐（零硬编码主题色）：
+ *  - 列边框不再硬编码蓝（移除原 #99bbe8 单线描边）；Panel 列回归原生 .x-panel 边框
+ *    （蓝/灰随 xtheme 主题切换），裸列（node 模式）视觉完全由调用方提供（中性或借原生类）。
+ *  - 响应式增强：width 未显式传入时，以 useLayoutEffect + ResizeObserver 测量
+ *    .x-column-inner 内容宽作为 pw 起点，使 Portal 等响应式场景无需硬写容器宽。
+ */
+export const ColumnLayout: FC<ColumnLayoutProps> = (props) => {
+  const {
+    width: propWidth,
+    items,
+    testId,
+    style,
+    className = '',
+    defaultMargins = '0',
+  } = props;
+
+  const rootRef = useRef<HTMLDivElement | null>(null);
+  const innerRef = useRef<HTMLDivElement | null>(null);
+  const [measured, setMeasured] = useState(0);
+
+  // 响应式测量容器内容宽（仅当未显式传 width 时使用），对齐原生 getLayoutTargetSize。
+  // 必须测量根 .x-column-layout-ct：其宽度由父容器决定、不依赖 availW；若测 .x-column-inner
+  // （其 width 绑定 availW，首帧为 0）会形成「测到 0 → 保持 0」死循环，导致所有列宽塌成 0。
+  useLayoutEffect(() => {
+    const el = rootRef.current;
+    if (!el) return;
+    const measure = () => setMeasured(el.clientWidth);
+    measure();
+    const ro = new ResizeObserver(measure);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+
+  const defMar = parseMargins(defaultMargins);
+  // 显式 width 优先（兼容既有 demo / 测试），否则用测量值（响应式）
+  const availW = propWidth && propWidth > 0 ? propWidth : measured;
+
+  const { widths, marginList } = useMemo(() => {
+    const mList = items.map((it) => (it.margins ? parseMargins(it.margins) : defMar));
+    let pw = availW;
+    items.forEach((it, i) => {
+      if (it.columnWidth == null) {
+        pw -= (it.width ?? 0) + mList[i].left + mList[i].right;
+      }
+    });
+    pw = pw < 0 ? 0 : pw;
+    const w = items.map((it, i) => {
+      const m = mList[i];
+      if (it.columnWidth != null) {
+        return Math.floor(it.columnWidth * pw) - m.left - m.right;
+      }
+      return it.width ?? 0;
+    });
+    return { widths: w, marginList: mList };
+  }, [items, availW, defMar]);
+
+  return (
+    <div
+      ref={rootRef}
+      data-testid={testId}
+      className={['x-column-layout-ct', className].filter(Boolean).join(' ')}
+      style={style}
+    >
+      <div className="x-column-inner" ref={innerRef} style={{ width: availW }}>
+        {items.map((it, i) => {
+          const m = marginList[i];
+          const margStyle: CSSProperties =
+            m.top || m.right || m.bottom || m.left
+              ? { margin: `${m.top}px ${m.right}px ${m.bottom}px ${m.left}px` }
+              : {};
+
+          // —— 裸列模式：node 直接作为列内容，组件只负责算宽 + float；视觉外置 ——
+          if (it.node != null) {
+            return (
+              <div
+                key={it.dataId ?? i}
+                className={['x-column', it.cls].filter(Boolean).join(' ')}
+                data-dd-column
+                data-id={it.dataId}
+                style={{
+                  float: 'left',
+                  width: widths[i],
+                  ...margStyle,
+                  ...it.columnStyle,
+                }}
+              >
+                {it.node}
+              </div>
+            );
+          }
+
+          // —— Panel 列模式：列即 .x-panel，边框回退到原生 .x-panel（蓝/灰随 xtheme 主题切换），
+          //    不硬编码任何主题色。box-sizing:border-box 让 1px 边框画在 width 内侧，
+          //    各列宽精确相加得到容器宽、不溢出。 ——
+          return (
+            <Panel
+              key={i}
+              title={it.title}
+              cls={['x-column', it.cls].filter(Boolean).join(' ')}
+              width={widths[i]}
+              style={{ display: 'block', boxSizing: 'border-box', ...margStyle }}
+              bodyStyle={it.bodyStyle}
+            >
+              {it.html != null ? it.html : it.children}
+            </Panel>
+          );
+        })}
+      </div>
+    </div>
+  );
+};

package/src/components/ColumnTree.tsx

@@ -0,0 +1,383 @@
+/**
+ * Ext.ux.tree.ColumnTree / ColumnNodeUI 保真复刻（来源 examples/tree/column-tree.js、
+ * examples/ux/ColumnNodeUI.js、examples/ux/css/ColumnNodeUI.css）。
+ *
+ * 保真契约（DOM/class 严格对齐 Ext 3.2.1）：
+ *  - 面板根：div.x-panel.x-column-tree（+ 可选 cls），与 Ext Panel 同构。
+ *  - 面板头：div.x-panel-header
+ *      > span.x-panel-header-text（标题）
+ *      > div.x-tree-headers（列头行，width = 列总宽）
+ *          > div.x-tree-hd(.{c.cls}-hd) > div.x-tree-hd-text（每列一个）
+ *          > div.x-clear
+ *  - 面板体：div.x-panel-body（height 给定时 overflow:auto）
+ *      > div.x-tree.x-tree-no-lines（width = 列总宽）> ul.x-tree-root-ct
+ *          > li.x-tree-node（每个节点）
+ *              > div.x-tree-node-el（选中加 x-tree-selected；整行着色由 CSS 承担）
+ *                  > div.x-tree-col（首列：缩进 + ec 图标 + 节点图标 + anchor + 文本）
+ *                  > div.x-tree-col（其余列：x-tree-col-text）
+ *                  > div.x-clear
+ *              > ul.x-tree-node-ct（子节点；展开 block / 折叠 none）
+ *  - 列宽：每列 col / hd 的 outer 宽 = c.width（本项目全局 border-box，边框已含在 width 内，
+ *    与 Ext 在 isBorderBox 时 width = c.width 等价）；header 与数据列同宽，总宽与列模型一致。
+ *
+ * 行为契约：
+ *  - 展开/折叠：点击 ec-icon 切换 expanded（翻转 el 的 expanded/collapsed、ec 图标的 plus/minus、ct 的 display）。
+ *  - 选中：点击节点 → 加 x-tree-selected（同级唯一），移除兄弟选中。
+ *  - 悬停：onMouseEnter 加 x-tree-node-over，onMouseLeave 移除。
+ *  - 首列值：node.text 优先，否则 c.renderer 或 node[c.dataIndex]；其余列：c.renderer 或 node[c.dataIndex]。
+ */
+import React, { useState, useRef, useImperativeHandle, forwardRef, type CSSProperties } from 'react';
+
+// 与原版 Ext.BLANK_IMAGE_URL 等价（1x1 透明 gif），避免网络请求
+const BLANK =
+  'data:image/gif;base64,R0lGODlhAQABAID/AMDAwAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==';
+
+export interface ColumnTreeColumn {
+  /** 列头文本 */
+  header: string;
+  /** 数据字段名（首列缺省取 node.text，其余列取 node[dataIndex]） */
+  dataIndex: string;
+  /** 列宽（px） */
+  width: number;
+  /** 附加在列头 div 上的 class（渲染为 {cls}-hd） */
+  cls?: string;
+  /** 单元格渲染器：(value, node, node) => ReactNode，覆盖默认文本 */
+  renderer?: (value: unknown, node: ColumnTreeNode, attrs: ColumnTreeNode) => React.ReactNode;
+}
+
+export interface ColumnTreeNode {
+  /** 节点唯一 id（必填，供 key / 选中 / 命令式句柄定位） */
+  id: string;
+  /** 首列默认文本（缺省回退到首列 dataIndex 字段） */
+  text?: string;
+  /** 初始是否展开 */
+  expanded?: boolean;
+  /** 强制显示 +/- 展开柄（即使无子节点） */
+  expandable?: boolean;
+  /** 显式叶子（不显示展开柄） */
+  leaf?: boolean;
+  /** 初始是否禁用 */
+  disabled?: boolean;
+  /** 图标图片路径（覆盖默认空白图标） */
+  icon?: string;
+  /** 图标 class（加到 x-tree-node-icon 上，由 CSS 提供背景图） */
+  iconCls?: string;
+  /** 附加 class（落在 x-tree-node-el 上） */
+  cls?: string;
+  /** 子节点 */
+  children?: ColumnTreeNode[];
+  /** 其余列数据字段 */
+  [key: string]: unknown;
+}
+
+export interface ColumnTreeProps {
+  /** 面板标题（落在 x-panel-header-text） */
+  title?: string;
+  /** 面板宽度（px） */
+  width?: number;
+  /** 面板高度（px），设置后启用体滚动区 */
+  height?: number;
+  /** 列模型（必填） */
+  columns: ColumnTreeColumn[];
+  /** 顶层节点数组 */
+  nodes?: ColumnTreeNode[];
+  /** 根节点（与 nodes 二选一；rootVisible:false 时仅用其 children） */
+  root?: ColumnTreeNode;
+  /** 是否显示根节点，默认 false（对齐 Ext ColumnTree 示例 rootVisible:false） */
+  rootVisible?: boolean;
+  /** 是否显示连接线（ColumnTree 默认 false → x-tree-no-lines） */
+  lines?: boolean;
+  /** 启用体滚动区（对齐 Ext autoScroll） */
+  autoScroll?: boolean;
+  /** 追加在面板根上的 class */
+  cls?: string;
+  /** 选中节点回调（参数为节点对象） */
+  onSelect?: (node: ColumnTreeNode) => void;
+  /** 展开/折叠回调 */
+  onExpand?: (node: ColumnTreeNode, expanded: boolean) => void;
+  /** 透传到 .x-panel-body 的 inline style */
+  bodyStyle?: CSSProperties;
+}
+
+export interface ColumnTreeHandle {
+  /** 读取当前根层节点数组（实时快照） */
+  getNodes: () => ColumnTreeNode[];
+  /** 展开节点 */
+  expand: (id: string) => void;
+  /** 折叠节点 */
+  collapse: (id: string) => void;
+  /** 切换展开/折叠 */
+  toggle: (id: string) => void;
+  /** 选中节点 */
+  select: (id: string) => void;
+  /** 当前选中节点 id（无选中返回 null） */
+  getSelected: () => string | null;
+}
+
+// 盒模型对齐：本项目全局 box-sizing:border-box（Ext 3 默认 content-box）。
+// border-box 下列 outer 宽即配置 width（边框已含在 width 内），故 ΔborderWidth = 0，
+// 与 Ext 在 isBorderBox 时为列设置 width = c.width 等价。
+const BORDER_WIDTH = 0;
+
+interface RenderCtx {
+  columns: ColumnTreeColumn[];
+  expandedIds: Record<string, boolean>;
+  selectedId: string | null;
+  ancestorsLast: boolean[];
+  onSelect: (node: ColumnTreeNode) => void;
+  onToggle: (id: string, node: ColumnTreeNode) => void;
+}
+
+function ColumnBranch({
+  node,
+  isLast,
+  ctx,
+}: {
+  node: ColumnTreeNode;
+  isLast: boolean;
+  ctx: RenderCtx;
+}) {
+  const [hovered, setHovered] = useState(false);
+
+  const children = node.children;
+  const hasChildren = !!children && children.length > 0;
+  const expandable = (hasChildren || node.expandable === true) && node.leaf !== true;
+  const expanded = !!ctx.expandedIds[node.id];
+  const selected = ctx.selectedId === node.id;
+  const disabled = !!node.disabled;
+
+  // el 状态 class
+  const elCls = [
+    'x-tree-node-el',
+    expandable ? (expanded ? 'x-tree-node-expanded' : 'x-tree-node-collapsed') : 'x-tree-node-leaf',
+    hovered && !disabled ? 'x-tree-node-over' : '',
+    selected ? 'x-tree-selected' : '',
+    disabled ? 'x-tree-node-disabled' : '',
+    'x-unselectable',
+    node.cls || '',
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  // ec-icon：自身末位 → x-tree-elbow-end，否则 x-tree-elbow；可展开加 -plus/-minus
+  const ecBase = isLast ? 'x-tree-elbow-end' : 'x-tree-elbow';
+  const ecSuffix = expandable ? (expanded ? '-minus' : '-plus') : '';
+  const ecCls = ['x-tree-ec-icon', `${ecBase}${ecSuffix}`].join(' ');
+
+  const iconCls = [
+    'x-tree-node-icon',
+    node.icon ? 'x-tree-node-inline-icon' : '',
+    node.iconCls || '',
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  // 祖先缩进：每个祖先非末位 → x-tree-elbow-line，末位 → x-tree-icon
+  const indentImgs = ctx.ancestorsLast.map((aLast) =>
+    aLast ? 'x-tree-icon' : 'x-tree-elbow-line',
+  );
+
+  const handleSelect = () => {
+    if (disabled) return;
+    ctx.onSelect(node);
+  };
+  const handleEcClick = (e: React.MouseEvent) => {
+    e.stopPropagation();
+    if (disabled || !expandable) return;
+    ctx.onToggle(node.id, node);
+  };
+
+  const firstCol = ctx.columns[0];
+  const firstValue =
+    node.text !== undefined
+      ? node.text
+      : firstCol.renderer
+        ? firstCol.renderer(node[firstCol.dataIndex], node, node)
+        : (node[firstCol.dataIndex] ?? '');
+
+  return (
+    <li className="x-tree-node">
+      <div
+        className={elCls}
+        unselectable="on"
+        data-node-id={node.id}
+        onMouseEnter={() => setHovered(true)}
+        onMouseLeave={() => setHovered(false)}
+        onClick={handleSelect}
+      >
+        {/* 首列：缩进 + ec 图标 + 节点图标 + anchor + 文本 */}
+        <div className="x-tree-col" style={{ width: firstCol.width - BORDER_WIDTH }}>
+          <span className="x-tree-node-indent">
+            {indentImgs.map((c, i) => (
+              <img key={i} src={BLANK} className={c} alt="" />
+            ))}
+          </span>
+          <img src={BLANK} className={ecCls} alt="" onClick={handleEcClick} />
+          <img
+            src={node.icon || BLANK}
+            className={iconCls}
+            unselectable="on"
+            alt=""
+          />
+          <a className="x-tree-node-anchor" href="#" tabIndex={1} onClick={(e) => e.preventDefault()}>
+            <span unselectable="on">{firstValue as React.ReactNode}</span>
+          </a>
+        </div>
+        {/* 其余列 */}
+        {ctx.columns.slice(1).map((c) => {
+          const value = c.renderer
+            ? c.renderer(node[c.dataIndex], node, node)
+            : (node[c.dataIndex] ?? '');
+          return (
+            <div
+              key={c.dataIndex}
+              className={`x-tree-col ${c.cls || ''}`}
+              style={{ width: c.width - BORDER_WIDTH }}
+            >
+              <div className="x-tree-col-text">{value as React.ReactNode}</div>
+            </div>
+          );
+        })}
+        <div className="x-clear" />
+      </div>
+      {(hasChildren || node.expandable === true) && (
+        <ul className="x-tree-node-ct" style={{ display: expanded ? 'block' : 'none' }}>
+          {hasChildren &&
+            children!.map((child, i) => (
+              <ColumnBranch
+                key={child.id}
+                node={child}
+                isLast={i === children!.length - 1}
+                ctx={{ ...ctx, ancestorsLast: [...ctx.ancestorsLast, isLast] }}
+              />
+            ))}
+        </ul>
+      )}
+    </li>
+  );
+}
+
+export const ColumnTree = forwardRef<ColumnTreeHandle, ColumnTreeProps>(function ColumnTree(
+  {
+    title,
+    width,
+    height,
+    columns,
+    nodes,
+    root,
+    rootVisible = false,
+    lines = false,
+    autoScroll = true,
+    cls = '',
+    onSelect,
+    onExpand,
+    bodyStyle,
+  },
+  ref,
+) {
+  const topNodes = React.useMemo<ColumnTreeNode[]>(() => {
+    if (nodes) return nodes;
+    if (root) return rootVisible ? [root] : root.children ?? [];
+    return [];
+  }, [nodes, root, rootVisible]);
+
+  const [expandedIds, setExpandedIds] = useState<Record<string, boolean>>(() => {
+    const acc: Record<string, boolean> = {};
+    const walk = (ns: ColumnTreeNode[]) => {
+      ns.forEach((n) => {
+        if (n.expanded) acc[n.id] = true;
+        if (n.children) walk(n.children);
+      });
+    };
+    walk(topNodes);
+    return acc;
+  });
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const topNodesRef = useRef<ColumnTreeNode[]>(topNodes);
+  topNodesRef.current = topNodes;
+
+  useImperativeHandle(ref, () => ({
+    getNodes: () => topNodesRef.current,
+    expand: (id) => setExpandedIds((prev) => ({ ...prev, [id]: true })),
+    collapse: (id) => setExpandedIds((prev) => ({ ...prev, [id]: false })),
+    toggle: (id) =>
+      setExpandedIds((prev) => {
+        const next = { ...prev };
+        next[id] = !next[id];
+        return next;
+      }),
+    select: (id) => setSelectedId(id),
+    getSelected: () => selectedId,
+  }));
+
+  const totalWidth = columns.reduce((s, c) => s + c.width, 0);
+
+  const ctx: RenderCtx = {
+    columns,
+    expandedIds,
+    selectedId,
+    ancestorsLast: [],
+    onSelect: (node) => {
+      setSelectedId(node.id);
+      onSelect?.(node);
+    },
+    onToggle: (id, node) => {
+      const willExpand = !expandedIds[id];
+      setExpandedIds((prev) => ({ ...prev, [id]: willExpand }));
+      onExpand?.(node, willExpand);
+    },
+  };
+
+  const showHeader = !!title;
+  const rootCls = lines ? 'x-tree-lines' : 'x-tree-no-lines';
+
+  return (
+    <div
+      className={['x-panel', 'x-column-tree', cls].filter(Boolean).join(' ')}
+      style={{ width: width ?? totalWidth, height }}
+    >
+      {showHeader && (
+        <div className="x-panel-header" unselectable="on">
+          {title && <span className="x-panel-header-text">{title}</span>}
+          <div className="x-tree-headers" style={{ width: totalWidth }}>
+            {columns.map((c) => (
+              <div
+                key={c.dataIndex}
+                className={`x-tree-hd ${c.cls ? c.cls + '-hd' : ''}`}
+                style={{ width: c.width - BORDER_WIDTH }}
+              >
+                <div className="x-tree-hd-text">{c.header}</div>
+              </div>
+            ))}
+            <div className="x-clear" />
+          </div>
+        </div>
+      )}
+      <div
+        className="x-panel-body"
+        style={{
+          ...bodyStyle,
+          overflowX: 'hidden',
+          overflowY: height != null && autoScroll ? 'auto' : undefined,
+        }}
+      >
+        <div className={`x-tree ${rootCls}`} style={{ width: totalWidth }}>
+          <ul className={`x-tree-root-ct ${rootCls}`}>
+            {topNodes.map((n, i) => (
+              <ColumnBranch
+                key={n.id}
+                node={n}
+                isLast={i === topNodes.length - 1}
+                ctx={ctx}
+              />
+            ))}
+          </ul>
+        </div>
+      </div>
+    </div>
+  );
+});
+
+ColumnTree.displayName = 'ColumnTree';
+
+export default ColumnTree;