react-extjs 0.0.1

package/src/components/Menu.tsx

@@ -0,0 +1,227 @@
+import React, {
+  forwardRef,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+
+/**
+ * 菜单项定义（保真复刻 Ext.menu.Item / Ext.menu.Separator 的常用字段）。
+ */
+export interface MenuItem {
+  text?: string;
+  iconCls?: string;
+  disabled?: boolean;
+  /** 为 true 时渲染为分隔线（li.x-menu-sep-li > span.x-menu-sep） */
+  separator?: boolean;
+  /** 点击回调（等价 Ext 的 handler） */
+  handler?: () => void;
+  /** 子菜单项（存在则本项渲染 x-menu-item-arrow，hover 时右侧展开子菜单） */
+  menu?: MenuItem[];
+  /** 单/多选标记（Ext.menu.CheckItem：渲染 x-menu-item-checked，x-cycle-menu 下高亮背景） */
+  checked?: boolean;
+  /**
+   * 自定义渲染内容（对齐 Ext.menu.Item 承载任意内容 / Ext.menu.Adapter）。
+   * 传入则不渲染标准 icon+text，直接在 a.x-menu-item 内渲染该节点——
+   * 用于 GridFilters 等需要在菜单内嵌入文本框/数字区间/日期/复选列表的插件。
+   */
+  render?: React.ReactNode | (() => React.ReactNode);
+}
+
+export interface MenuProps {
+  items: MenuItem[];
+  onItemClick?: (item: MenuItem, index: number) => void;
+  /** 根容器附加样式（子菜单用它定位，如 position/left/top/zIndex） */
+  style?: React.CSSProperties;
+  /** 根容器附加 class（如 x-cycle-menu），用于 CycleButton 菜单高亮 */
+  rootClassName?: string;
+  /** 演示/测试用：强制常开指定索引的子菜单（默认 undefined，仍由 hover 控制）。 */
+  submenuAlwaysOpen?: number;
+  /** 透传 ref：暴露 add / remove / getItems / getSubmenu（对齐 Ext.menu.Menu.add / remove）。 */
+  ref?: React.Ref<MenuHandle>;
+}
+
+/**
+ * Menu 命令句柄（对齐 Ext.menu.Menu.add / remove）。
+ *  - add(item, id?)：追加一项到当前项列表尾部，返回稳定 id（便于后续 remove）。
+ *  - remove(id)：按 id 移除一项。
+ *  - getItems()：返回当前项列表（含 id），顺序为 [原始 items, 动态追加项]。
+ *  - getSubmenu(id)：返回指定项（其 menu 子菜单）的 MenuHandle，便于对级联子菜单动态增删；
+ *    仅在该子菜单已渲染（常开或 hover 展开）时可用，否则返回 undefined。
+ */
+export interface MenuHandle {
+  add: (item: MenuItem, id?: string) => string;
+  remove: (id: string) => void;
+  getItems: () => Array<{ id: string; item: MenuItem }>;
+  getSubmenu: (id: string) => MenuHandle | undefined;
+}
+
+/** 内部受管项：在原始项之外附加稳定 id 以支持动态增删。 */
+interface ManagedItem {
+  id: string;
+  item: MenuItem;
+}
+
+/**
+ * Menu —— 保真复刻 Ext.menu.Menu（src/widgets/menu/Menu.js onRender 193-200 + Item.js itemTpl）。
+ *
+ * 保真契约（DOM/class 严格对齐源码）：
+ *  - 根：x-menu x-menu-floating x-layer（绝对定位，z-index 15000）
+ *  - a.x-menu-focus（隐藏聚焦元素，等同 onRender 198）+ ul.x-menu-list
+ *  - 普通项：li.x-menu-list-item > a.x-menu-item[ x-menu-item-arrow][ cls] hidefocus unselectable href="#"
+ *              > img.x-menu-item-icon {iconCls} + span.x-menu-item-text
+ *  - 分隔项：li.x-menu-sep-li > span.x-menu-sep（Separator.js 38）
+ *  - 子菜单：项含 menu 时 <a> 加 x-menu-item-arrow（Item.js 36749，CSS 引 menu-parent.gif），
+ *            hover（onMouseOver）时在 li 右侧展开嵌套 .x-menu（position:absolute left:100% top:0）。
+ *  - 状态：hover -> li.x-menu-item-active（onMouseOver 309）；disabled -> li.x-menu-item-disabled
+ *
+ * 交互（行为契约）：点击项 -> 执行 handler + 触发 onItemClick（onClick 255）；
+ * 关闭逻辑由外层（如 Button）统一管理（外部点击 / Esc / 点项）。
+ */
+export const Menu = forwardRef<MenuHandle, MenuProps>((
+  { items, onItemClick, style, rootClassName, submenuAlwaysOpen },
+  ref,
+) => {
+  const [active, setActive] = useState<number | null>(null);
+  const [openSub, setOpenSub] = useState<number | null>(null);
+
+  // items prop 恒为静态项来源（受控）；动态增删只影响独立的 dynamicItems 状态，
+  // 绝不会被 prop 变更冲掉。未开动态时 managed === items，DOM 完全一致（像素基线零回归）。
+  const [dynamicItems, setDynamicItems] = useState<ManagedItem[]>([]);
+  const [removedStatic, setRemovedStatic] = useState<Set<string>>(new Set());
+  const seqRef = useRef(0);
+  // 登记各子菜单（按父项 id）的句柄，供 getSubmenu 动态增删级联子菜单。
+  const submenuRefs = useRef<Map<string, MenuHandle>>(new Map());
+
+  const managed = useMemo<ManagedItem[]>(
+    () => [
+      ...items
+        .map((it, i) => ({ id: `seed-${i}`, item: it }))
+        .filter((m) => !removedStatic.has(m.id)),
+      ...dynamicItems,
+    ],
+    [items, dynamicItems, removedStatic],
+  );
+
+  useImperativeHandle(ref, () => ({
+    add: (item, id) => {
+      const newId = id ?? `mi-${++seqRef.current}`;
+      setDynamicItems((prev) => [...prev, { id: newId, item }]);
+      return newId;
+    },
+    remove: (id) => {
+      // 动态追加项从 dynamicItems 删除；原始 seed 项登记到 removedStatic（对齐 Ext menu.remove 可删任意项）
+      if (id.startsWith('seed-')) {
+        setRemovedStatic((prev) => {
+          const next = new Set(prev);
+          next.add(id);
+          return next;
+        });
+      } else {
+        setDynamicItems((prev) => prev.filter((m) => m.id !== id));
+      }
+    },
+    getItems: () => managed,
+    getSubmenu: (id) => submenuRefs.current.get(id),
+  }), [managed]);
+
+  return (
+    <div
+      className={['x-menu x-menu-floating x-layer', rootClassName].filter(Boolean).join(' ')}
+      style={{ position: 'absolute', zIndex: 15000, visibility: 'visible', ...style }}
+    >
+      <a href="#" className="x-menu-focus" tabIndex={-1} onClick={(e) => e.preventDefault()} />
+      {/* 级联子菜单以嵌套 DOM 渲染在 li 内（便于 hover 进入），但 .x-menu-list 默认
+          overflow:hidden 会裁切延伸到右侧的子菜单。当有子菜单展开时临时放开 overflow，
+          逃出裁切；关闭后恢复 CSS 默认值（兼容启用滚动的长菜单）。 */}
+      <ul className="x-menu-list" style={openSub !== null ? { overflow: 'visible' } : undefined}>
+        {managed.map((m, i) => {
+          const it = m.item;
+          return it.separator ? (
+            <li className="x-menu-sep-li" key={m.id} data-menu-id={m.id}>
+              <span className="x-menu-sep" />
+            </li>
+          ) : (
+            <li
+              className={[
+                'x-menu-list-item',
+                it.disabled ? 'x-menu-item-disabled' : '',
+                it.checked !== undefined ? 'x-menu-item-check-item' : '',
+                it.checked ? 'x-menu-item-checked' : '',
+                active === i ? 'x-menu-item-active' : '',
+              ]
+                .filter(Boolean)
+                .join(' ')}
+              key={m.id}
+              data-menu-id={m.id}
+              style={{ position: 'relative' }}
+              onMouseEnter={() => {
+                if (it.disabled) return;
+                setActive(i);
+                if (it.menu) setOpenSub(i); // hover 展开子菜单（对齐 Ext onMouseOver 显示子菜单）
+              }}
+              onMouseLeave={() => {
+                setActive((a) => (a === i ? null : a));
+                setOpenSub((s) => (s === i ? null : s)); // 子菜单是 li 后代，移入子菜单不触发 leave
+              }}
+            >
+              <a
+                href="#"
+                className={['x-menu-item', it.menu ? 'x-menu-item-arrow' : ''].filter(Boolean).join(' ')}
+                tabIndex={-1}
+                unselectable="on"
+                onClick={(e) => {
+                  e.preventDefault();
+                  if (it.disabled) return;
+                  it.handler?.();
+                  onItemClick?.(it, i);
+                }}
+              >
+                {it.render ? (
+                  <span
+                    onClick={(e) => e.stopPropagation()}
+                    style={{ display: 'block' }}
+                  >
+                    {(typeof it.render === 'function'
+                      ? (it.render as () => React.ReactNode)()
+                      : it.render)}
+                  </span>
+                ) : (
+                  <>
+                    {(it.iconCls || it.checked !== undefined) && (
+                      <img src="/extjs-assets/images/default/s.gif" className={`x-menu-item-icon ${it.iconCls || ''}`} />
+                    )}
+                    <span className="x-menu-item-text">{it.text}</span>
+                  </>
+                )}
+              </a>
+              {it.menu && (
+                <Menu
+                  ref={(h) => {
+                    if (h) submenuRefs.current.set(m.id, h);
+                    else submenuRefs.current.delete(m.id);
+                  }}
+                  items={it.menu}
+                  onItemClick={onItemClick}
+                  style={{
+                    left: '100%',
+                    top: 0,
+                    zIndex: 15001,
+                    // 始终挂载子菜单（display 控制显隐），使 getSubmenu(id) 在任意时刻、任意层级
+                    // 都可用——对齐 Ext「item.menu 实例始终存在、可随时 .add()」的标准特性，
+                    // 无需子菜单处于 hover/展开状态即可对其动态增删（含新增子菜单）。
+                    display: openSub === i || submenuAlwaysOpen === i ? 'block' : 'none',
+                  }}
+                />
+              )}
+            </li>
+          );
+        })}
+      </ul>
+    </div>
+  );
+});
+Menu.displayName = 'Menu';
+
+export default Menu;

package/src/components/MessageBox.tsx

@@ -0,0 +1,138 @@
+import React, { useState, forwardRef, useImperativeHandle } from 'react';
+import { Window, type WindowHandle } from './Window';
+
+/**
+ * MessageBox —— 保真复刻 Ext.MessageBox（Ext.Msg.show 的对话框外观）。
+ *
+ * 保真契约（DOM/class 严格对齐 Ext 3.2.1 运行时，由 dump golden 校验）：
+ *  - 外层即 Ext.Window（plain），根追加 x-window-dlg 类；autoHeight（高度由内容撑开）。
+ *  - header：x-tool-close（closable 时）+ span.x-window-header-text（与 Window 一致）。
+ *  - body（x-window-body，padding 5px 10px）唯一子节点为 x-dlg-icon（有图标时）包裹：
+ *        div.ext-mb-icon.ext-mb-<icon>（无图标时省略，x-dlg-icon 类也省略）
+ *        div.ext-mb-content（有图标时 margin-left:47px）
+ *          > span.ext-mb-text + br + div.ext-mb-fix-cursor(input.ext-mb-input + textarea.ext-mb-textarea，均 display:none)
+ *        div.x-progress-wrap.x-hide-display（隐藏，结构占位）
+ *        div.x-clear
+ *  - footer：x-window-footer.x-panel-btns > Toolbar(rootClass x-panel-fbar ...，buttonAlign center) 居中按钮。
+ *  - 末尾：a.x-dlg-focus（Window 已含）。
+ *
+ * 说明：Ext.MessageBox 本身 modal 遮罩覆盖 document.body；此处仅复刻对话框外观（遮罩不影响对话框像素），
+ *       行为用例聚焦对话框内图标/文本/按钮，遮罩不纳入像素对比。
+ */
+
+export type MessageBoxIcon = 'question' | 'info' | 'warning' | 'error';
+
+export interface MessageBoxButton {
+  text: string;
+  /** 按钮宽度（像素），对齐 Ext.MessageBox 按钮的 width 配置 */
+  width?: number;
+  /** 点击回调；返回 false 可阻止对话框自动关闭（对齐 Ext MessageBox 按钮语义） */
+  onClick?: () => boolean | void;
+}
+
+export interface MessageBoxProps {
+  title?: string;
+  /** 正文文本 */
+  msg: string;
+  width?: number;
+  icon?: MessageBoxIcon;
+  /** 是否显示右上角关闭按钮（默认 true，对齐 Ext MessageBox 默认 closable:true） */
+  closable?: boolean;
+  /** 底部按钮（按数组顺序渲染，居中）。留空则不渲染 footer */
+  buttons?: MessageBoxButton[];
+  /** 点击右上角关闭（或 closable）时的回调 */
+  onClose?: () => void;
+  className?: string;
+}
+
+/** 命令式句柄：运行时改写标题/正文/图标，以及 show/hide（转发底层 Window） */
+export interface MessageBoxHandle {
+  /** 改写窗口标题（转发 Window.setTitle） */
+  setTitle: (t: string) => void;
+  /** 运行时改写正文 */
+  setMessage: (m: string) => void;
+  /** 运行时改写图标（'question' | 'info' | 'warning' | 'error' | undefined） */
+  setIcon: (i?: MessageBoxIcon) => void;
+  /** 显示对话框（转发 Window.open） */
+  show: () => void;
+  /** 隐藏对话框（转发 Window.close） */
+  hide: () => void;
+  /** 当前是否可见 */
+  isVisible: () => boolean;
+}
+
+export const MessageBox = forwardRef<MessageBoxHandle, MessageBoxProps>(function MessageBox(
+  { title, msg, width = 400, icon, closable = true, buttons, onClose, className },
+  ref,
+) {
+  // 双轨：msg / icon 由自身 state 管理；title / 可见性转发底层 Window 句柄
+  const [dynMsg, setDynMsg] = useState(msg);
+  const [dynIcon, setDynIcon] = useState(icon);
+  const winRef = React.useRef<WindowHandle>(null);
+
+  const setTitle = React.useCallback((t: string) => winRef.current?.setTitle(t), []);
+  const setMessage = React.useCallback((m: string) => setDynMsg(m), []);
+  const setIcon = React.useCallback((i?: MessageBoxIcon) => setDynIcon(i), []);
+  const show = React.useCallback(() => winRef.current?.open(), []);
+  const hide = React.useCallback(() => winRef.current?.close(), []);
+  const isVisible = React.useCallback(() => winRef.current?.isVisible() ?? false, []);
+  // 点击 X（closable）时：先关闭对话框（转发 Window.close），再触发用户 onClose 回调，对齐 Ext 行为
+  const handleClose = React.useCallback(() => {
+    winRef.current?.close();
+    onClose?.();
+  }, [onClose]);
+
+  useImperativeHandle(
+    ref,
+    () => ({ setTitle, setMessage, setIcon, show, hide, isVisible }),
+    [setTitle, setMessage, setIcon, show, hide, isVisible],
+  );
+
+  const rootCls = ['x-window-dlg', className].filter(Boolean).join(' ');
+
+  const dlgIconCls = dynIcon ? 'x-dlg-icon' : '';
+  const iconEl = dynIcon ? <div className={`ext-mb-icon ext-mb-${dynIcon}`} /> : null;
+
+  const bodyContent = (
+    <div className={dlgIconCls}>
+      {iconEl}
+      <div className="ext-mb-content">
+        <span className="ext-mb-text">{dynMsg}</span>
+        <br />
+        <div className="ext-mb-fix-cursor">
+          <input type="text" className="ext-mb-input" style={{ display: 'none' }} />
+          <textarea className="ext-mb-textarea" style={{ display: 'none' }} />
+        </div>
+      </div>
+      <div className="x-progress-wrap x-hide-display" />
+      <div className="x-clear" />
+    </div>
+  );
+
+  return (
+    <Window
+      ref={winRef}
+      title={title}
+      width={width}
+      plain
+      autoHeight
+      className={rootCls}
+      footerAlign="center"
+      closable={closable}
+      buttons={(buttons ?? []).map((b) => ({
+        text: b.text,
+        width: b.width,
+        // 点击按钮：先执行用户回调；回调未返回 false 则自动关闭对话框（对齐 Ext MessageBox 按钮语义）
+        onClick: () => {
+          const r = b.onClick?.();
+          if (r !== false) winRef.current?.close();
+        },
+      }))}
+      onClose={handleClose}
+    >
+      {bodyContent}
+    </Window>
+  );
+});
+
+export default MessageBox;