react-extjs 0.0.1

package/src/components/TabPanel.tsx

@@ -0,0 +1,540 @@
+import React, {
+  forwardRef,
+  useCallback,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { createPortal } from 'react-dom';
+import { Menu, type MenuItem } from './Menu';
+
+/**
+ * TabPanel —— 保真复刻 Ext.TabPanel（src/widgets/TabPanel.js）。
+ *
+ * 保真契约（DOM/class 严格对齐源码）：
+ *  - 外层：x-tab-panel（baseCls='x-tab-panel'）
+ *  - 头部：x-panel-header x-tab-panel-header [x-tab-panel-header-plain]
+ *        └ x-tab-strip-wrap > ul.x-tab-strip.x-tab-strip-{top|bottom}
+ *             ├ li（每个 tab）
+ *             │   cls: [x-tab-strip-closable][x-item-disabled][x-tab-with-icon] [tabCls]
+ *             │   激活: x-tab-strip-active    hover: x-tab-strip-over
+ *             │   <a class="x-tab-strip-close">（可关闭时）
+ *             │   <a class="x-tab-right" href="#"><em class="x-tab-left">
+ *             │     <span class="x-tab-strip-inner">
+ *             │       <span class="x-tab-strip-text {iconCls}">{title}</span>
+ *             │     </span></em></a>
+ *             ├ li.x-tab-edge > span.x-tab-strip-text (&#160;)
+ *             └ div.x-clear
+ *        └ div.x-tab-strip-spacer
+ *  - 主体：x-panel-body x-tab-panel-body x-tab-panel-body-{top|bottom}
+ *        （非激活 tab 内容用 x-hide-display 隐藏，等价 Ext CardLayout）
+ *
+ * 交互（行为契约）：
+ *  - 点击 tab → setActiveTab：旧 li 去 x-tab-strip-active，新 li 加（源码 setActiveTab 814/820）
+ *  - hover → 切换 x-tab-strip-over（仅未禁用；源码 initTab 520）
+ *  - 可关闭：点击 x-tab-strip-close → beforeclose/close → 移除该 tab（源码 onStripMouseDown 466）
+ *  - 禁用 tab 不可激活（源码 findTargets 444）
+ *  - 键盘：←/→ 切换激活、Enter/Space 激活（现代化升级，等价于 Ext 把键盘 click 路由到 onStripMouseDown）
+ *  - onBeforeTabChange 返回 false 可取消切换（源码 setActiveTab 803）
+ *  - 动态增删：add(item,id?) / remove(key) / removeAt(index) / activate(key) 对齐 Ext
+ *    TabPanel.add/remove 容器 API（items prop 恒为静态项来源 + 独立 dynamic 状态，双轨，保真零回归）。
+ */
+export interface TabItem {
+  id?: string;
+  title: string;
+  iconCls?: string;
+  closable?: boolean;
+  disabled?: boolean;
+  tabCls?: string;
+  content: React.ReactNode;
+}
+
+export interface TabPanelProps {
+  items: TabItem[];
+  activeTab?: number;
+  tabPosition?: 'top' | 'bottom';
+  plain?: boolean;
+  border?: boolean;
+  /** 启用 tab 溢出滚动（对齐 Ext.TabPanel.enableTabScroll，默认 false）。tabs 总宽超过容器时渲染左右滚动箭头。 */
+  enableTabScroll?: boolean;
+  /** TabCloseMenu 插件：右键 tab 弹出关闭菜单（关闭/关闭其他/关闭全部），尊重 closable。 */
+  closeMenu?: boolean;
+  /** TabScrollerMenu 插件：enableTabScroll 且出现滚动条时，滚动箭头旁出现下拉菜单按钮，列出全部 tab 跳转。 */
+  scrollerMenu?: boolean;
+  width?: number | string;
+  height?: number | string;
+  onTabChange?: (index: number) => void;
+  onBeforeTabChange?: (index: number) => boolean;
+  onClose?: (index: number) => void;
+}
+
+export interface TabPanelHandle {
+  /** 追加一个 tab，返回其稳定 key（缺省时自动生成）。默认不激活，可传 activate=true 激活。 */
+  add: (item: TabItem, id?: string, activate?: boolean) => string;
+  /** 按 key 移除（key 即 add 返回的字符串，或静态项 'seed-<i>'）。 */
+  remove: (key: string) => void;
+  /** 按「合并后列表」的 index 移除（与 onClose 回调的 index 一致）。 */
+  removeAt: (index: number) => void;
+  /** 按 key 激活某个 tab。 */
+  activate: (key: string) => void;
+  /** 取当前存活（未移除）的 tab 列表（含动态项）。 */
+  getItems: () => TabItem[];
+}
+
+const buildTabCls = (item: TabItem): string => {
+  let cls = item.closable ? 'x-tab-strip-closable' : '';
+  if (item.disabled) cls += ' x-item-disabled';
+  if (item.iconCls) cls += ' x-tab-with-icon';
+  if (item.tabCls) cls += ' ' + item.tabCls;
+  return cls.trim();
+};
+
+interface ManagedTab {
+  key: string;
+  item: TabItem;
+}
+
+export const TabPanel = forwardRef<TabPanelHandle, TabPanelProps>(function TabPanel(
+  {
+    items,
+    activeTab = 0,
+    tabPosition = 'top',
+    plain = false,
+    border = true,
+    enableTabScroll = false,
+    closeMenu = false,
+    scrollerMenu = false,
+    width,
+    height,
+    onTabChange,
+    onBeforeTabChange,
+    onClose,
+  },
+  ref,
+) {
+  const [activeIndex, setActiveIndex] = useState(activeTab);
+  const [hovered, setHovered] = useState<number | null>(null);
+  // removed 基于 managed key（双轨：items 为静态源，dynamic 为运行时追加）
+  const [removed, setRemoved] = useState<Set<string>>(new Set());
+  const [dynamic, setDynamic] = useState<ManagedTab[]>([]);
+  const seqRef = useRef(0);
+
+  // —— 插件：TabCloseMenu —— 右键 tab 弹出关闭菜单
+  const [ctxMenu, setCtxMenu] = useState<{ x: number; y: number; index: number } | null>(null);
+  const ctxMenuRef = useRef<HTMLDivElement>(null);
+
+  // —— 插件：TabScrollerMenu —— 滚动条旁下拉菜单按钮，列出全部 tab
+  const [scrollerMenuOpen, setScrollerMenuOpen] = useState<{ x: number; y: number } | null>(null);
+  const scrollerMenuRef = useRef<HTMLDivElement>(null);
+
+  // 统一关闭浮层菜单（外部点击 / Esc）
+  React.useEffect(() => {
+    if (!ctxMenu && !scrollerMenuOpen) return;
+    const onDown = (e: MouseEvent) => {
+      const t = e.target as HTMLElement;
+      if (ctxMenuRef.current && ctxMenuRef.current.contains(t)) return;
+      if (scrollerMenuRef.current && scrollerMenuRef.current.contains(t)) return;
+      setCtxMenu(null);
+      setScrollerMenuOpen(null);
+    };
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        setCtxMenu(null);
+        setScrollerMenuOpen(null);
+      }
+    };
+    document.addEventListener('mousedown', onDown);
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('mousedown', onDown);
+      document.removeEventListener('keydown', onKey);
+    };
+  }, [ctxMenu, scrollerMenuOpen]);
+
+  const staticManaged = useMemo(
+    () => items.map((it, i) => ({ key: `seed-${i}`, item: it })),
+    [items],
+  );
+  const managed = useMemo<ManagedTab[]>(
+    () => [...staticManaged, ...dynamic],
+    [staticManaged, dynamic],
+  );
+
+  // 合并列表索引（含已移除占位）即「managed index」，非动态场景恒等于原始 items index。
+  const visibleItems = useMemo(
+    () =>
+      managed
+        .map((m, i) => ({ ...m, i }))
+        .filter(({ key }) => !removed.has(key)),
+    [managed, removed],
+  );
+
+  const activate = useCallback(
+    (index: number) => {
+      const m = managed[index];
+      if (!m || index === activeIndex) return;
+      if (m.item.disabled) return;
+      if (onBeforeTabChange && onBeforeTabChange(index) === false) return;
+      setActiveIndex(index);
+      onTabChange?.(index);
+    },
+    [managed, activeIndex, onBeforeTabChange, onTabChange],
+  );
+
+  const close = useCallback(
+    (index: number) => {
+      const m = managed[index];
+      if (!m?.item.closable) return;
+      onClose?.(index);
+      setRemoved((prev) => {
+        const next = new Set(prev);
+        next.add(m.key);
+        // 激活相邻 tab（优先右侧，否则左侧），与 Ext onRemove 624 行为一致
+        if (index === activeIndex) {
+          const remaining = visibleItems
+            .map(({ i }) => i)
+            .filter((i) => i !== index);
+          const neighbor = remaining[0] ?? 0;
+          setActiveIndex(neighbor);
+        }
+        return next;
+      });
+    },
+    [managed, activeIndex, visibleItems, onClose],
+  );
+
+  // —— 插件：TabCloseMenu 的「关闭其他 / 关闭全部」辅助 ——
+  const closeOthers = useCallback(
+    (index: number) => {
+      managed.forEach((_, i) => {
+        if (i !== index) close(i);
+      });
+      setActiveIndex(index);
+      setCtxMenu(null);
+    },
+    [managed, close],
+  );
+  const closeAll = useCallback(() => {
+    managed.forEach((_, i) => close(i));
+    setCtxMenu(null);
+  }, [managed, close]);
+
+  // —— 插件：TabCloseMenu 右键菜单项 ——
+  const ctxMenuItems: MenuItem[] = ctxMenu
+    ? [
+        { text: '关闭', handler: () => { close(ctxMenu.index); setCtxMenu(null); } },
+        { text: '关闭其他', handler: () => closeOthers(ctxMenu.index) },
+        { text: '关闭全部', handler: () => closeAll() },
+      ]
+    : [];
+
+  // —— 插件：TabScrollerMenu 下拉项（列出全部 tab）——
+  const scrollMenuItems: MenuItem[] = scrollerMenuOpen
+    ? visibleItems.map(({ item, i }) => ({
+        text: item.title,
+        disabled: i === activeIndex,
+        handler: () => {
+          activate(i);
+          setScrollerMenuOpen(null);
+        },
+      }))
+    : [];
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      add: (item, id, activateTab) => {
+        const key = id ?? `tab-${++seqRef.current}`;
+        // 新 tab 追加在末尾，其 managed index = 静态项数 + 当前动态项数（追加前）
+        const newIndex = staticManaged.length + dynamic.length;
+        setDynamic((prev) => [...prev, { key, item }]);
+        if (activateTab) setActiveIndex(newIndex);
+        return key;
+      },
+      remove: (key) => {
+        const idx = managed.findIndex((m) => m.key === key);
+        if (idx >= 0) close(idx);
+      },
+      removeAt: (index) => close(index),
+      activate: (key) => {
+        const idx = managed.findIndex((m) => m.key === key);
+        if (idx >= 0) activate(idx);
+      },
+      getItems: () =>
+        managed.filter((m) => !removed.has(m.key)).map((m) => m.item),
+    }),
+    [managed, dynamic, staticManaged, close, activate, removed],
+  );
+
+  // Tab 溢出滚动（对齐 Ext.TabPanel enableTabScroll + TabStrip 的 scroller）：
+  // 当 ul.x-tab-strip 内容总宽超过 scroll-wrap 可见宽时，渲染左右滚动箭头。
+  const stripWrapRef = React.useRef<HTMLDivElement>(null);
+  const stripRef = React.useRef<HTMLUListElement>(null);
+  const [scroller, setScroller] = React.useState(false);
+  const [scrollPos, setScrollPos] = React.useState(0);
+  const [scrollMeta, setScrollMeta] = React.useState<{ max: number; leftDisabled: boolean; rightDisabled: boolean }>({
+    max: 0,
+    leftDisabled: true,
+    rightDisabled: false,
+  });
+
+  // 箭头高度与 strip-wrap（tab item 区）等高，对齐 Ext.TabPanel 源码
+  // scroller.setSize(undefined, stripWrap.getHeight()) 行为
+  const [arrowHeight, setArrowHeight] = React.useState<number | undefined>(undefined);
+
+  const measureScroll = React.useCallback(() => {
+    const wrap = stripWrapRef.current;
+    const strip = stripRef.current;
+    if (!wrap || !strip) return;
+    const max = Math.max(0, strip.scrollWidth - wrap.clientWidth);
+    setScroller(strip.scrollWidth - wrap.clientWidth > 1);
+    setScrollMeta({ max, leftDisabled: scrollPos <= 0, rightDisabled: scrollPos >= max });
+  }, [scrollPos]);
+
+  // 初次 / tabs 变化时判定是否需滚动；scroller 出现后 strip-wrap 自动 margin 18（见 CSS），
+  // 因此 clientWidth 变小，需在 scroller 切换后重新测量一次。
+  React.useLayoutEffect(() => {
+    if (!enableTabScroll) return;
+    measureScroll();
+  }, [enableTabScroll, visibleItems.length, scroller, measureScroll]);
+
+  // 同步 scrollLeft 到 DOM（对齐 Ext.scrollToTab 的 scroll-wrap.scrollLeft 调整）
+  React.useLayoutEffect(() => {
+    if (stripWrapRef.current) stripWrapRef.current.scrollLeft = scrollPos;
+  }, [scrollPos, scroller]);
+
+  // 同步箭头高度到 strip-wrap（对齐源码 scroller.setSize(undefined, stripWrap.getHeight)）
+  React.useLayoutEffect(() => {
+    if (!enableTabScroll || !stripWrapRef.current) return;
+    setArrowHeight(stripWrapRef.current.offsetHeight);
+  }, [enableTabScroll, visibleItems.length]);
+
+  const scrollBy = (delta: number) => {
+    const wrap = stripWrapRef.current;
+    const strip = stripRef.current;
+    if (!wrap || !strip) return;
+    const max = Math.max(0, strip.scrollWidth - wrap.clientWidth);
+    const next = Math.max(0, Math.min(max, scrollPos + delta));
+    setScrollPos(next);
+  };
+
+  const onKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (e.key !== 'ArrowLeft' && e.key !== 'ArrowRight') return;
+      e.preventDefault();
+      const dir = e.key === 'ArrowRight' ? 1 : -1;
+      const list = visibleItems.map(({ i }) => i);
+      const pos = list.indexOf(activeIndex);
+      for (let step = 1; step <= list.length; step++) {
+        const cand = list[(pos + dir * step + list.length) % list.length];
+        if (!managed[cand].item.disabled) {
+          activate(cand);
+          break;
+        }
+      }
+    },
+    [visibleItems, activeIndex, managed, activate],
+  );
+
+  const renderStrip = (position: 'top' | 'bottom') => {
+    return (
+      <>
+        {scroller && (
+          <div
+            className={`x-tab-scroller-left${scrollMeta.leftDisabled ? ' x-tab-scroller-left-disabled' : ''}`}
+            style={{ height: arrowHeight }}
+            onClick={() => !scrollMeta.leftDisabled && scrollBy(-120)}
+          />
+        )}
+        {/* 对齐 Ext onRender 324-325：bottom 时 x-tab-strip-spacer 插在 strip-wrap 之前，top 时在其后 */}
+        {position === 'bottom' && <div className="x-tab-strip-spacer" />}
+        <div
+          className="x-tab-strip-wrap"
+          ref={stripWrapRef}
+          style={{ overflow: 'hidden', marginRight: scroller && scrollerMenu ? 36 : undefined }}
+        >
+          <ul
+            ref={stripRef}
+            className={`x-tab-strip x-tab-strip-${position}`}
+            role="tablist"
+            onKeyDown={onKeyDown}
+          >
+            {visibleItems.map(({ key, item, i }) => {
+              const cls = [
+                buildTabCls(item),
+                i === activeIndex ? 'x-tab-strip-active' : '',
+                hovered === i && !item.disabled ? 'x-tab-strip-over' : '',
+              ]
+                .filter(Boolean)
+                .join(' ');
+              return (
+                <li
+                  key={key}
+                  id={item.id}
+                  className={cls}
+                  role="tab"
+                  aria-selected={i === activeIndex}
+                  tabIndex={i === activeIndex ? 0 : -1}
+                  onMouseEnter={() => setHovered(i)}
+                  onMouseLeave={() => setHovered((h) => (h === i ? null : h))}
+                  onClick={() => activate(i)}
+                  onContextMenu={
+                    closeMenu
+                      ? (e) => {
+                          e.preventDefault();
+                          setCtxMenu({ x: e.clientX, y: e.clientY, index: i });
+                        }
+                      : undefined
+                  }
+                >
+                  <a
+                    className="x-tab-strip-close"
+                    onClick={(e) => {
+                      e.stopPropagation();
+                      if (item.closable) close(i);
+                    }}
+                  />
+                  <a className="x-tab-right" href="#" onClick={(e) => e.preventDefault()}>
+                    <em className="x-tab-left">
+                      <span className="x-tab-strip-inner">
+                        <span className={`x-tab-strip-text ${item.iconCls || ''}`}>
+                          {item.title}
+                        </span>
+                      </span>
+                    </em>
+                  </a>
+                </li>
+              );
+            })}
+            <li className="x-tab-edge">
+              <span className="x-tab-strip-text">&#160;</span>
+            </li>
+            <div className="x-clear" style={{ width: 0 }} />
+          </ul>
+        </div>
+        {scroller && (
+          <div
+            className={`x-tab-scroller-right${scrollMeta.rightDisabled ? ' x-tab-scroller-right-disabled' : ''}`}
+            style={{
+              height: arrowHeight,
+              ...(scrollerMenu ? { right: 18 } : {}),
+            }}
+            onClick={() => !scrollMeta.rightDisabled && scrollBy(120)}
+          />
+        )}
+        {scroller && scrollerMenu && (
+          <div
+            className="x-tab-tabmenu-right"
+            style={{ height: arrowHeight, bottom: 'auto' }}
+            onClick={(e) => {
+              const r = (e.currentTarget as HTMLElement).getBoundingClientRect();
+              setScrollerMenuOpen({ x: r.left, y: r.bottom });
+            }}
+          />
+        )}
+        {position === 'top' && <div className="x-tab-strip-spacer" />}
+      </>
+    );
+  };
+
+  const scrollerMod = tabPosition === 'bottom' ? 'x-tab-scrolling-bottom' : 'x-tab-scrolling-top';
+  // 对齐原始 Ext.TabPanel：tabPosition==='bottom' 时用 footer 元素
+  // （this.pos = footer，见 TabPanel.js），footer 含 padding-top:2px，
+  // 避免 strip 被顶到上边框。
+  const stripBaseCls = tabPosition === 'bottom' ? 'x-tab-panel-footer' : 'x-tab-panel-header';
+  const plainCls = plain
+    ? tabPosition === 'bottom'
+      ? 'x-tab-panel-footer-plain'
+      : 'x-tab-panel-header-plain'
+    : '';
+  // border:false 时 header/footer 也加 -noborder（对齐 Ext：x-tab-panel-header-noborder）。
+  const noborderCls = border ? '' : `${stripBaseCls}-noborder`;
+  const headerCls = [
+    stripBaseCls,
+    noborderCls,
+    'x-unselectable',
+    plainCls,
+    scroller ? `x-tab-scrolling ${scrollerMod}` : '',
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  // 对齐 Ext Panel 结构（onRender）：body 由 baseCls+'-body' 命名，底部无 header 时加
+  // x-tab-panel-body-noheader（Ext 源码 addClass('x-panel-body-noheader' 分支），与 body-{pos} 对应。
+  const bodyCls = [
+    'x-panel-body',
+    'x-tab-panel-body',
+    tabPosition === 'bottom' ? 'x-tab-panel-body-noheader' : '',
+    `x-tab-panel-body-${tabPosition}`,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  const rootCls = ['x-tab-panel', border ? '' : 'x-tab-panel-noborder'].filter(Boolean).join(' ');
+
+  // 对齐 Ext 结构：面板 root 下是 x-tab-panel-bwrap 包裹体（Panel.js body wrap），
+  // top 时 header 是 root 直接子元素、body 在 bwrap 内；bottom 时 footer 也在 bwrap 内、
+  // 排在 body 之后（见真实 Ext 运行时 DOM）。bwrap/body 用内联 flex 撑满，
+  // 复现 Ext 由 layout 计算 body 高度（height - docked 高度）的效果，使 footer 贴底、不悬空。
+  const rootStyle: React.CSSProperties = { width, height, display: 'flex', flexDirection: 'column' };
+  const bwrapStyle: React.CSSProperties = {
+    display: 'flex',
+    flexDirection: 'column',
+    flex: '1 1 auto',
+    minHeight: 0,
+  };
+  const bodyStyle: React.CSSProperties = { flex: '1 1 auto', minHeight: 0 };
+
+  return (
+    <div className={rootCls} style={rootStyle}>
+      {tabPosition === 'top' && (
+        <div className={headerCls}>
+          {renderStrip('top')}
+        </div>
+      )}
+      <div className="x-tab-panel-bwrap" style={bwrapStyle}>
+        <div className={bodyCls} style={bodyStyle}>
+          {visibleItems.map(({ key, item, i }) => (
+            <div
+              key={key}
+              role="tabpanel"
+              className={i === activeIndex ? '' : 'x-hide-display'}
+            >
+              {item.content}
+            </div>
+          ))}
+        </div>
+        {tabPosition === 'bottom' && (
+          <div className={headerCls}>
+            {renderStrip('bottom')}
+          </div>
+        )}
+      </div>
+
+      {createPortal(
+        <>
+          {ctxMenu && (
+            <div
+              ref={ctxMenuRef}
+              style={{ position: 'absolute', left: ctxMenu.x, top: ctxMenu.y, zIndex: 15000 }}
+            >
+              <Menu items={ctxMenuItems} />
+            </div>
+          )}
+          {scrollerMenuOpen && (
+            <div
+              ref={scrollerMenuRef}
+              style={{ position: 'absolute', left: scrollerMenuOpen.x, top: scrollerMenuOpen.y, zIndex: 15000 }}
+            >
+              <Menu items={scrollMenuItems} />
+            </div>
+          )}
+        </>,
+        document.body,
+      )}
+    </div>
+  );
+});
+
+export default TabPanel;

package/src/components/TableLayout.tsx

@@ -0,0 +1,132 @@
+import React from 'react';
+import { Panel } from './Panel';
+
+export interface TableItem {
+  title?: string;
+  /** 子 Panel 正文（对齐 Ext Panel.html，作为 body 直接子节点） */
+  html?: string;
+  width?: number;
+  height?: number;
+  frame?: boolean;
+  /** 跨列数（对齐 Ext item.colspan） */
+  colspan?: number;
+  /** 跨行数（对齐 Ext item.rowspan） */
+  rowspan?: number;
+  /** 附加在 td 上的 class（对齐 Ext item.cellCls） */
+  cellCls?: string;
+  /** body 内边距（透传给子 Panel 的 bodyPadding） */
+  bodyPadding?: number | string;
+}
+
+export interface TableLayoutProps {
+  title?: string;
+  width?: number;
+  /** 列数（对齐 Ext layoutConfig.columns） */
+  columns: number;
+  items: TableItem[];
+  frame?: boolean;
+  testId?: string;
+  style?: React.CSSProperties;
+}
+
+interface Placement {
+  item: TableItem;
+  row: number;
+  col: number;
+  colspan: number;
+  rowspan: number;
+}
+
+/**
+ * 保真映射（来源 Ext.layout.TableLayout + Ext.Panel）：
+ * - 根 Panel 的 body 加 `x-table-layout-ct`（target.addClass，见 onLayout 113 行）。
+ * - body 直接子节点为 `<table class="x-table-layout" cellspacing="0">` > `<tbody>` > `<tr>` > `<td class="x-table-layout-cell">`。
+ * - 放置算法逐行移植 getNextNonSpan(163)/getNextCell(132)：
+ *     cells 占用图 + 从当前 (col,row) 推进到下一个空闲格（col>=columns 则换行 col=0）；
+ *     标记矩形占用后创建 td（带 colspan/rowspan/cellCls），append 到对应 row 的 tr。
+ *   **关键**：仅对“起始行”创建 <tr>（rowspan 跨越的行不产生 tr，由浏览器隐式延续），
+ *   每行内 td 按“列递增”顺序（即 item 处理顺序）append——与 Ext 完全一致；空缺格不生成占位 td。
+ * - 无任何专属 CSS 规则（ext-all.css 无 .x-table-layout*），视觉纯来自浏览器默认表格渲染 +
+ *   单元格内 Panel 自身样式；td padding 0、content-box，故只要结构复制一致即像素一致。
+ */
+export function TableLayout({ title, width, columns, items, frame = false, testId, style }: TableLayoutProps) {
+  const placements: Placement[] = React.useMemo(() => {
+    const cells: boolean[][] = [];
+    let curCol = 0;
+    let curRow = 0;
+    const out: Placement[] = [];
+
+    const getNextNonSpan = (colIndex: number, rowIndex: number): [number, number] => {
+      while ((columns && colIndex >= columns) || (cells[rowIndex] && cells[rowIndex][colIndex])) {
+        if (columns && colIndex >= columns) {
+          rowIndex += 1;
+          colIndex = 0;
+        } else {
+          colIndex += 1;
+        }
+      }
+      return [colIndex, rowIndex];
+    };
+
+    for (const item of items) {
+      const colspan = item.colspan || 1;
+      const rowspan = item.rowspan || 1;
+      const [c, r] = getNextNonSpan(curCol, curRow);
+      curCol = c;
+      curRow = r;
+      for (let ri = r; ri < r + rowspan; ri += 1) {
+        if (!cells[ri]) cells[ri] = [];
+        for (let ci = c; ci < c + colspan; ci += 1) {
+          cells[ri][ci] = true;
+        }
+      }
+      out.push({ item, row: r, col: c, colspan, rowspan });
+    }
+    return out;
+  }, [items, columns]);
+
+  // 仅“起始行”需要 <tr>，按升序；行内 td 保持处理顺序（列递增）即与 Ext 一致
+  const startRows = Array.from(new Set(placements.map((p) => p.row))).sort((a, b) => a - b);
+  const byRow = (r: number) => placements.filter((p) => p.row === r);
+
+  const renderItem = (item: TableItem) => (
+    <Panel
+      title={item.title}
+      width={item.width}
+      height={item.height}
+      frame={item.frame ?? true}
+      bodyPadding={item.bodyPadding ?? 0}
+    >
+      {item.html !== undefined ? (
+        <span dangerouslySetInnerHTML={{ __html: item.html }} />
+      ) : null}
+    </Panel>
+  );
+
+  return (
+    <div data-testid={testId} style={style}>
+      <Panel title={title} width={width} frame={frame} bodyClassName="x-table-layout-ct">
+        <table className="x-table-layout" cellSpacing={0}>
+          <tbody>
+            {startRows.map((r) => (
+              <tr key={r}>
+                {byRow(r).map((p, i) => (
+                  <td
+                    key={i}
+                    className={['x-table-layout-cell', p.item.cellCls].filter(Boolean).join(' ')}
+                    colSpan={p.colspan > 1 ? p.colspan : undefined}
+                    rowSpan={p.rowspan > 1 ? p.rowspan : undefined}
+                  >
+                    {renderItem(p.item)}
+                  </td>
+                ))}
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </Panel>
+    </div>
+  );
+}
+
+export default TableLayout;