react-extjs 0.0.1

package/src/components/Toolbar.tsx

@@ -0,0 +1,321 @@
+import React, { forwardRef, useImperativeHandle, useMemo, useRef, useState } from 'react';
+import { Button, type ButtonProps } from './Button';
+import { type MenuItem } from './Menu';
+
+/**
+ * Toolbar —— 保真复刻 Ext.Toolbar（src/widgets/Toolbar.js + layout/ToolbarLayout.js）。
+ *
+ * 保真契约（DOM/class 严格对齐源码）：
+ *  - 根：x-toolbar x-small-editor x-toolbar-layout-ct
+ *        （onRender 加 x-small-editor；ToolbarLayout.onLayout 给 target 加 x-toolbar-layout-ct）
+ *  - 布局表（tableHTML，ToolbarLayout 47-83 行）：
+ *        table.x-toolbar-ct
+ *          tbody > tr
+ *            td.x-toolbar-left[align=left|center]   ← buttonAlign 决定 align
+ *              table > tbody > tr.x-toolbar-left-row
+ *                td.x-toolbar-cell（每个 item）        ← insertCell 165 行
+ *            td.x-toolbar-right[align=right]
+ *              table.x-toolbar-right-ct
+ *                tbody > tr > td
+ *                  table > tbody > tr.x-toolbar-right-row（fill '->' 之后的 item）
+ *                td
+ *                  table > tbody > tr.x-toolbar-extras-row（overflow 'more' 按钮，默认空）
+ *  - item 类型（lookupComponent 197-221 行）：
+ *        '-'  / {xtype:'tbseparator'}  → span.xtb-sep          （Separator.onRender 462）
+ *        ' '  / {xtype:'tbspacer'}     → div.xtb-spacer[style width]（Spacer.onRender 500）
+ *        '->' / {xtype:'tbfill'}       → 切换右侧容器（Fill 不渲染，只作为分隔标记）
+ *        字符串 / {xtype:'tbtext'}     → div.xtb-text           （TextItem.onRender 558）
+ *        {xtype:'button'|'tbbutton'} 或带 text 的对象 → 渲染 Button 组件
+ *        ReactNode（字段/任意元素）      → 直接放入 td.x-toolbar-cell
+ *
+ * 交互（行为契约）：
+ *  - 按钮点击/菜单：委托给 Button 组件（与 buttons 用例同一实现）
+ *  - '->' 之后项目右对齐（rightTr），之前项目按 buttonAlign 左/居中
+ */
+export type ToolbarAlign = 'left' | 'center' | 'right';
+
+export interface ToolbarButtonConfig extends Omit<ButtonProps, 'text'> {
+  text?: string;
+  xtype?: 'button' | 'tbbutton';
+}
+interface ToolbarTextConfig {
+  xtype: 'tbtext';
+  text: string;
+  /** 追加在 .xtb-text 之外的额外 class（如 StatusBar 的 x-status-text + iconCls） */
+  cls?: string;
+}
+interface ToolbarSeparatorConfig {
+  xtype: 'tbseparator';
+}
+interface ToolbarSpacerConfig {
+  xtype: 'tbspacer';
+  width?: number;
+}
+interface ToolbarFillConfig {
+  xtype: 'tbfill';
+}
+
+export type ToolbarItem =
+  | string
+  | ToolbarButtonConfig
+  | ToolbarTextConfig
+  | ToolbarSeparatorConfig
+  | ToolbarSpacerConfig
+  | ToolbarFillConfig
+  | React.ReactNode;
+
+export interface ToolbarProps {
+  items: ToolbarItem[];
+  /** 左/中区域的水平对齐，等价 Ext buttonAlign */
+  buttonAlign?: ToolbarAlign;
+  width?: number | string;
+  style?: React.CSSProperties;
+  className?: string;
+  /** 数据测试 id，挂在根 div 上（供保真截图/行为测试定位） */
+  testId?: string;
+  /** 覆盖根 class（默认 x-toolbar x-small-editor x-toolbar-layout-ct）。
+   *  用于 Window.footer 等需要 x-panel-fbar 根类的场景。 */
+  rootClass?: string;
+  /** 溢出菜单（x-toolbar-more）：为 true 时在 extras-row 渲染 more 按钮，
+   *  点击展开菜单显示 overflowItems。对齐 Ext.Toolbar enableOverflow。 */
+  enableOverflow?: boolean;
+  /** 收进 more 菜单的项（按钮/分隔符）。对齐 Ext 溢出检测隐藏的后缀项。 */
+  overflowItems?: ToolbarItem[];
+  /** 透传 ref：暴露 add / remove / getItems（对齐 Ext.Toolbar.add / remove）。 */
+  ref?: React.Ref<ToolbarHandle>;
+}
+
+/**
+ * Toolbar 命令句柄（对齐 Ext.Toolbar.add / remove）。
+ *  - add(item, id?)：追加一项到当前项列表尾部，返回稳定 id（便于后续 remove）。
+ *  - remove(id)：按 id 移除一项。
+ *  - getItems()：返回当前项列表（含 id）。
+ */
+export interface ToolbarHandle {
+  add: (item: ToolbarItem, id?: string) => string;
+  remove: (id: string) => void;
+  getItems: () => Array<{ id: string; item: ToolbarItem }>;
+}
+
+/** 内部受管项：在原始项之外附加稳定 id 以支持动态增删。 */
+interface ManagedItem {
+  id: string;
+  item: ToolbarItem;
+}
+
+/** 将溢出项转换为 Menu 的项（仅保留文本/分隔/图标/禁用，对齐 Ext.createMenuConfig） */
+const toMenuItems = (items: ToolbarItem[]): MenuItem[] =>
+  items.map((it) => {
+    if (typeof it === 'string') {
+      if (it === '-') return { separator: true };
+      return { text: it };
+    }
+    if (it && typeof it === 'object' && !React.isValidElement(it)) {
+      const o = it as Record<string, unknown>;
+      if (o.xtype === 'tbseparator') return { separator: true };
+      return {
+        text: String(o.text ?? ''),
+        disabled: Boolean(o.disabled),
+        iconCls: o.iconCls as string | undefined,
+        handler: o.handler as (() => void) | undefined,
+      };
+    }
+    return { text: '' };
+  });
+
+type Classified =
+  | { kind: 'separator' }
+  | { kind: 'spacer'; width?: number }
+  | { kind: 'fill' }
+  | { kind: 'text'; text: string; cls?: string }
+  | { kind: 'button'; config: ToolbarButtonConfig }
+  | { kind: 'raw'; node: React.ReactNode };
+
+const classify = (item: ToolbarItem): Classified => {
+  if (React.isValidElement(item)) return { kind: 'raw', node: item };
+  if (typeof item === 'string') {
+    if (item === '-') return { kind: 'separator' };
+    if (item === ' ') return { kind: 'spacer' };
+    if (item === '->') return { kind: 'fill' };
+    return { kind: 'text', text: item };
+  }
+  if (item && typeof item === 'object') {
+    const o = item as Record<string, unknown>;
+    if (o.xtype === 'tbseparator') return { kind: 'separator' };
+    if (o.xtype === 'tbspacer') return { kind: 'spacer', width: o.width as number | undefined };
+    if (o.xtype === 'tbfill') return { kind: 'fill' };
+    if (o.xtype === 'tbtext') return { kind: 'text', text: String(o.text ?? ''), cls: o.cls as string | undefined };
+    if (o.xtype === 'button' || o.xtype === 'tbbutton') {
+      return { kind: 'button', config: item as ToolbarButtonConfig };
+    }
+    // 带 text 的对象视为按钮配置（Ext.lookupComponent 197-221 的默认分支）
+    if ('text' in o) return { kind: 'button', config: item as ToolbarButtonConfig };
+  }
+  return { kind: 'raw', node: item as React.ReactNode };
+};
+
+const renderItem = (c: Classified, key: number): React.ReactNode => {
+  switch (c.kind) {
+    case 'separator':
+      return <span key={key} className="xtb-sep" />;
+    case 'spacer':
+      return (
+        <div
+          key={key}
+          className="xtb-spacer"
+          style={c.width ? { width: `${c.width}px` } : undefined}
+        />
+      );
+    case 'text':
+      return (
+        <div key={key} className={c.cls ? `xtb-text ${c.cls}` : 'xtb-text'}>
+          {c.text}
+        </div>
+      );
+    case 'button':
+      return <Button key={key} {...c.config} />;
+    case 'raw':
+      return <React.Fragment key={key}>{c.node}</React.Fragment>;
+    default:
+      return null;
+  }
+};
+
+// Ext.Toolbar 通过 BoxComponent.setSize() 扣除 frame（padding+border）设置 el.style.width。
+// .x-toolbar 有 padding:2px 左右 → 扣减 4px 使总宽度等于配置值。
+const adjustWidth = (w?: number | string): number | string | undefined => {
+  if (typeof w === 'number') return w - 4;
+  return w;
+};
+
+export const Toolbar = forwardRef<ToolbarHandle, ToolbarProps>((
+  {
+    items,
+    buttonAlign = 'left',
+    width,
+    style,
+    className,
+    testId,
+    rootClass,
+    enableOverflow,
+    overflowItems,
+  },
+  ref,
+) => {
+  // 受管项：初始由 items prop 播种（id=seed-N），运行时 add/remove 维护。
+  // items prop 始终是静态项的来源（保持受控，PagingToolbar 等会随状态重建 items）；
+  // 动态增删只影响独立的 dynamicItems 状态，绝不会被 prop 变更冲掉。
+  // 未开启动态增删时 managed === items，与原渲染完全等价（DOM 结构一致，像素基线零回归）。
+  const [dynamicItems, setDynamicItems] = useState<ManagedItem[]>([]);
+  const seqRef = useRef(0);
+
+  const managed = useMemo<ManagedItem[]>(
+    () => [
+      ...items.map((it, i) => ({ id: `seed-${i}`, item: it })),
+      ...dynamicItems,
+    ],
+    [items, dynamicItems],
+  );
+
+  useImperativeHandle(ref, () => ({
+    add: (item, id) => {
+      const newId = id ?? `tb-${++seqRef.current}`;
+      setDynamicItems((prev) => [...prev, { id: newId, item }]);
+      return newId;
+    },
+    remove: (id) => {
+      setDynamicItems((prev) => prev.filter((m) => m.id !== id));
+    },
+    getItems: () => managed,
+  }), [managed]);
+
+  const adjustedWidth = adjustWidth(width);
+  // 按第一个 fill('->') 切分左右区域；无 fill 则全部落入左侧
+  const left: ManagedItem[] = [];
+  const right: ManagedItem[] = [];
+  let onRight = false;
+  for (const m of managed) {
+    const c = classify(m.item);
+    if (c.kind === 'fill') {
+      onRight = true;
+      continue;
+    }
+    (onRight ? right : left).push(m);
+  }
+
+  const align = buttonAlign === 'center' ? 'center' : 'left';
+
+  const rootCls = rootClass
+    ?? [
+         'x-toolbar',
+         'x-small-editor',
+         'x-toolbar-layout-ct',
+         className,
+       ]
+         .filter(Boolean)
+         .join(' ');
+
+  const hasOverflow = Boolean(enableOverflow && overflowItems && overflowItems.length > 0);
+  const moreMenuItems = hasOverflow ? toMenuItems(overflowItems!) : undefined;
+
+  const renderCells = (list: ManagedItem[]) =>
+    list.map((m) => (
+      <td key={m.id} className="x-toolbar-cell" data-tool-id={m.id}>
+        {renderItem(classify(m.item), 0)}
+      </td>
+    ));
+
+  return (
+    <div className={rootCls} data-testid={testId} style={{ width: adjustedWidth, ...style }}>
+      <table cellSpacing={0} className="x-toolbar-ct">
+        <tbody>
+          <tr>
+            <td className="x-toolbar-left" align={align}>
+              <table cellSpacing={0}>
+                <tbody>
+                  <tr className="x-toolbar-left-row">{renderCells(left)}</tr>
+                </tbody>
+              </table>
+            </td>
+            <td className="x-toolbar-right" align="right">
+              <table cellSpacing={0} className="x-toolbar-right-ct">
+                <tbody>
+                  <tr>
+                    <td>
+                      <table cellSpacing={0}>
+                        <tbody>
+                          <tr className="x-toolbar-right-row">{renderCells(right)}</tr>
+                        </tbody>
+                      </table>
+                    </td>
+                    <td>
+                      <table cellSpacing={0}>
+                        <tbody>
+                          <tr className="x-toolbar-extras-row">
+                            {hasOverflow && moreMenuItems && (
+                              <td className="x-toolbar-cell">
+                                <Button
+                                  cls="x-toolbar-more"
+                                  iconCls="x-toolbar-more-icon"
+                                  text=" "
+                                  menu={moreMenuItems}
+                                />
+                              </td>
+                            )}
+                          </tr>
+                        </tbody>
+                      </table>
+                    </td>
+                  </tr>
+                </tbody>
+              </table>
+            </td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+  );
+});
+Toolbar.displayName = 'Toolbar';
+
+export default Toolbar;