react-extjs 0.0.1

package/src/components/HtmlEditor.tsx

@@ -0,0 +1,391 @@
+import React, { forwardRef, useImperativeHandle } from 'react';
+import { Toolbar, type ToolbarItem, type ToolbarButtonConfig } from './Toolbar';
+import { ColorMenu } from './ColorMenu';
+
+/**
+ * HtmlEditor —— 保真复刻 Ext.form.HtmlEditor（src/widgets/form/HtmlEditor.js）。
+ *
+ * 保真契约（DOM/class 严格对齐源码）：
+ *  - onRender（423-448 行）：textarea（el）被 .x-html-editor-wrap 包一层，并注入 cn:.x-html-editor-tb 作为首个子节点；
+ *        createToolbar 把 Toolbar 渲染进 wrap.dom.firstChild（即 .x-html-editor-tb）；
+ *        createIFrame 末尾 append 一个 iframe（frameBorder=0、overflow=auto）。
+ *  - 故 DOM 顺序为：.x-html-editor-tb(Toolbar) → textarea.x-form-textarea.x-form-field.x-hidden → iframe。
+ *  - wrap：content-box + border:1px solid（ext-all.css 第 4458 行）。
+ *  - 工具栏项（createToolbar，201-365 行）：
+ *        bold/italic/underline（toggle）、-、increase/decreasefontsize（toggle）、-、
+ *        forecolor/backcolor（带 ColorMenu → 渲染下拉箭头，宽 32px）、-、
+ *        justifyleft/center/right（toggle）、-、createlink（toggle）、-、
+ *        insertorderedlist/insertunorderedlist（toggle）、-、sourceedit（toggle）。
+ *        共 14 按钮 + 7 分隔符；每个图标按钮 cls='x-btn-icon'、iconCls='x-edit-*'（tb-sprite.gif）。
+ *  - 图标由 .x-html-editor-tb .x-edit-*（ext-all.css 第 4466-4533 行）定位到 tb-sprite.gif 对应 16px 位置。
+ *  - 尺寸（实测契约）：容器 configWidth×configHeight 时，wrap 渲染为 520×204（border 各 1px）；
+ *        工具栏 27px，iframe 内联 518×171（内联元素底部 4px 间隙 → 内容 202 → 含边框 204）。
+ *        React 侧令 wrap 宽=configWidth、border-box、不显式设高（由内容自然撑开，精确等于 golden）；
+ *        iframe 显式 width=configWidth-2、height=configHeight-27-2。
+ *
+ * 交互（行为契约，对应 Ext HtmlEditor + Toolbar + Button）：
+ *  - 工具栏图标按钮：toggle 类点击切换 x-btn-pressed；forecolor/backcolor 带下拉箭头（ColorMenu 代理）。
+ *  - 源码编辑（sourceedit）按钮：点击在 design 模式（iframe，designMode 编辑区）与 source 模式
+ *    （textarea 显示 HTML 源码）间切换；切换为 source 时其余工具栏按钮禁用（对齐 Ext toggleSourceEdit 的 disableItems）。
+ *    默认 design 模式，与 golden 静态态一致（fidelity:htmleditor 零回归）。
+ *  - 实际编辑：iframe 开启 designMode，格式按钮（粗体/斜体/下划线/对齐/列表/链接）点击对编辑区执行
+ *    document.execCommand，并据 queryCommandState 同步按钮 pressed 态（对齐 Ext onEditorEvent + btn.updateState）。
+ *  - forecolor/backcolor 按钮：点击展开 ColorMenu（复用 ColorMenu + ColorPalette），选中颜色后
+ *    对编辑区执行 execCommand('forecolor'/'backcolor', color)（对齐 Ext 这两个按钮挂载 ColorMenu，
+ *    选中色调色板回调触发 document.execCommand 应用前景/背景色）。
+ */
+
+/** iconCls → execCommand 命令映射（对齐 Ext HtmlEditor 工具栏命令）。 */
+const FORMAT_CMD: Record<string, string> = {
+  'x-edit-bold': 'bold',
+  'x-edit-italic': 'italic',
+  'x-edit-underline': 'underline',
+  'x-edit-justifyleft': 'justifyleft',
+  'x-edit-justifycenter': 'justifycenter',
+  'x-edit-justifyright': 'justifyright',
+  'x-edit-insertorderedlist': 'insertorderedlist',
+  'x-edit-insertunorderedlist': 'insertunorderedlist',
+  'x-edit-createlink': 'createlink',
+};
+
+/** 工具栏图标项：cls='x-btn-icon'、iconCls='x-edit-*'；toggle 类 enableToggle，颜色类带箭头（menu=true）。 */
+const EDITOR_TOOLBAR: ToolbarItem[] = [
+  // 字体下拉（enableFont 默认 true）：Ext 用 Toolbar.Item 包裹 <select class="x-font-select">，
+  // 内含 5 个字体 option（defaultFont='tahoma' 选中）。
+  (() => (
+    <select className="x-font-select" defaultValue="tahoma">
+      {['Arial', 'Courier New', 'Tahoma', 'Times New Roman', 'Verdana'].map((f) => (
+        <option key={f} value={f.toLowerCase()} style={{ fontFamily: f }}>
+          {f}
+        </option>
+      ))}
+    </select>
+  ))(),
+  '-',
+  { xtype: 'button', cls: 'x-btn-icon', iconCls: 'x-edit-bold', enableToggle: true },
+  { xtype: 'button', cls: 'x-btn-icon', iconCls: 'x-edit-italic', enableToggle: true },
+  { xtype: 'button', cls: 'x-btn-icon', iconCls: 'x-edit-underline', enableToggle: true },
+  '-',
+  { xtype: 'button', cls: 'x-btn-icon', iconCls: 'x-edit-increasefontsize' },
+  { xtype: 'button', cls: 'x-btn-icon', iconCls: 'x-edit-decreasefontsize' },
+  '-',
+  { xtype: 'button', cls: 'x-btn-icon', iconCls: 'x-edit-forecolor', menu: true },
+  { xtype: 'button', cls: 'x-btn-icon', iconCls: 'x-edit-backcolor', menu: true },
+  '-',
+  { xtype: 'button', cls: 'x-btn-icon', iconCls: 'x-edit-justifyleft', enableToggle: true },
+  { xtype: 'button', cls: 'x-btn-icon', iconCls: 'x-edit-justifycenter', enableToggle: true },
+  { xtype: 'button', cls: 'x-btn-icon', iconCls: 'x-edit-justifyright', enableToggle: true },
+  '-',
+  { xtype: 'button', cls: 'x-btn-icon', iconCls: 'x-edit-createlink', enableToggle: true },
+  '-',
+  { xtype: 'button', cls: 'x-btn-icon', iconCls: 'x-edit-insertorderedlist', enableToggle: true },
+  { xtype: 'button', cls: 'x-btn-icon', iconCls: 'x-edit-insertunorderedlist', enableToggle: true },
+  '-',
+  { xtype: 'button', cls: 'x-btn-icon', iconCls: 'x-edit-sourceedit', enableToggle: true },
+];
+
+export interface HtmlEditorProps {
+  /** 编辑器宽（含 1px 边框），等同 Ext width。默认 520 */
+  width?: number;
+  /** 编辑器高（含 1px 边框），等同 Ext height。默认 200 */
+  height?: number;
+  /** 初始 HTML 内容（golden 用 textarea 承载，React 仅作隐藏回显，编辑区由 iframe 呈现） */
+  value?: string;
+  /** 是否禁用（设计模式关闭 + 根加 x-item-disabled） */
+  disabled?: boolean;
+  /** 数据测试 id，挂在根 div 上 */
+  testId?: string;
+  className?: string;
+}
+
+/** HtmlEditor 句柄：对齐 Ext.form.HtmlEditor 公共 API 的运行时子集。 */
+export interface HtmlEditorHandle {
+  /** 运行时写入 HTML 内容（重写 iframe 编辑区） */
+  setValue: (html: string) => void;
+  /** 读取当前编辑区 HTML */
+  getValue: () => string;
+  /** 设置禁用态 */
+  setDisabled: (b: boolean) => void;
+  /** 是否禁用 */
+  isDisabled: () => boolean;
+  /** 聚焦编辑区 */
+  focus: () => void;
+  /** 切换 design/source 源码模式 */
+  toggleSource: () => void;
+  /** 当前是否源码模式 */
+  isSource: () => boolean;
+  /** 运行时对编辑区执行 execCommand */
+  execCommand: (cmd: string, value?: string) => void;
+}
+
+export const HtmlEditor = forwardRef<HtmlEditorHandle, HtmlEditorProps>(function HtmlEditor(
+  { width = 520, height = 200, value = '', disabled, testId, className },
+  ref,
+) {
+  // 双轨：value/disabled 由 prop 初始化，句柄运行时改写，useEffect 同步 prop 变化。
+  const [dynValue, setDynValue] = React.useState(value ?? '');
+  const [dynDisabled, setDynDisabled] = React.useState(disabled ?? false);
+  React.useEffect(() => {
+    if (value !== undefined) setDynValue(value);
+  }, [value]);
+  React.useEffect(() => {
+    if (disabled !== undefined) setDynDisabled(disabled);
+  }, [disabled]);
+
+  // 工具栏实测高度 27px；iframe 高 = 配置高 - 工具栏 - 上下边框(各1px)；宽 = 配置宽 - 左右边框。
+  const TOOLBAR_H = 27;
+  const iframeW = width - 2;
+  const iframeH = height - TOOLBAR_H - 2;
+  // 源码编辑态：false=design（iframe 编辑区可见），true=source（textarea 显示 HTML 源码）。
+  // 默认 design，与 golden 静态态一致。
+  const [sourceMode, setSourceMode] = React.useState(false);
+  // 格式按钮 pressed 态（对齐 Ext btn.updateState：依据编辑区 queryCommandState 同步）。
+  const [formatStates, setFormatStates] = React.useState<Record<string, boolean>>({});
+  const iframeRef = React.useRef<HTMLIFrameElement>(null);
+  // 编辑区选区快照（对齐 Ext 工具栏命令前保持选区：点击按钮 mousedown 会令 iframe 失焦、选区丢失，
+  // 故在 selectionchange 时缓存 Range，执行命令前恢复）。
+  const savedRange = React.useRef<Range | null>(null);
+  // forecolor/backcolor 调色板浮层（对齐 Ext 这两个按钮挂载的 ColorMenu）：null 表示未展开。
+  const [colorMenu, setColorMenu] = React.useState<{ cmd: 'forecolor' | 'backcolor'; anchor: HTMLElement } | null>(null);
+  const colorAnchorRef = React.useRef<HTMLElement | null>(null);
+
+  // 初始化 iframe：写入初始 HTML 并开启 designMode（对齐 Ext createIFrame + syncValue）。
+  React.useEffect(() => {
+    const doc = iframeRef.current?.contentDocument;
+    if (!doc) return;
+    try {
+      doc.open();
+      doc.write(`<html><head></head><body>${dynValue}</body></html>`);
+      doc.close();
+      doc.designMode = dynDisabled ? 'off' : 'on';
+      const refresh = () => {
+        const next: Record<string, boolean> = {};
+        for (const cmd of Object.values(FORMAT_CMD)) {
+          try {
+            next[cmd] = doc.queryCommandState(cmd);
+          } catch {
+            next[cmd] = false;
+          }
+        }
+        setFormatStates(next);
+        // 缓存当前选区（仅限编辑区 body 内），供执行命令前恢复
+        try {
+          const sel = doc.defaultView?.getSelection?.();
+          if (sel && sel.rangeCount > 0) {
+            const r = sel.getRangeAt(0);
+            if (doc.body.contains(r.commonAncestorContainer)) savedRange.current = r.cloneRange();
+          }
+        } catch {
+          /* 选区快照失败可忽略 */
+        }
+      };
+      doc.addEventListener('keyup', refresh);
+      doc.addEventListener('mouseup', refresh);
+      doc.addEventListener('selectionchange', refresh);
+    } catch {
+      /* designMode 初始化失败（极旧环境）时静默降级，不影响静态保真 */
+    }
+  }, [dynValue, dynDisabled]);
+
+  // 对编辑区执行 execCommand（对齐 Ext 工具栏命令）：focus 编辑区后运行命令，并刷新按钮态。
+  // value 可选（如 fontname 传字体名、createlink 传 URL）。
+  const runCommand = React.useCallback((cmd: string, value?: string) => {
+    const doc = iframeRef.current?.contentDocument;
+    if (!doc) return;
+    try {
+      iframeRef.current?.focus();
+      const sel = doc.defaultView?.getSelection?.();
+      if (sel) {
+        sel.removeAllRanges();
+        if (savedRange.current) sel.addRange(savedRange.current);
+        else {
+          const r = doc.createRange();
+          r.selectNodeContents(doc.body);
+          sel.addRange(r);
+        }
+      }
+      const cmdValue = value !== undefined ? value : cmd === 'createlink' ? 'http://example.com' : undefined;
+      doc.execCommand(cmd, false, cmdValue);
+      const next: Record<string, boolean> = {};
+      for (const c of Object.values(FORMAT_CMD)) {
+        try {
+          next[c] = doc.queryCommandState(c);
+        } catch {
+          next[c] = false;
+        }
+      }
+      setFormatStates(next);
+    } catch {
+      /* 命令不可用时静默降级 */
+    }
+  }, []);
+
+  // 应用颜色命令（forecolor/backcolor）：对齐 Ext 调色板选中后 document.execCommand(cmd, false, color)。
+  const runColorCommand = React.useCallback((cmd: 'forecolor' | 'backcolor', color: string) => {
+    const doc = iframeRef.current?.contentDocument;
+    if (!doc) return;
+    try {
+      iframeRef.current?.focus();
+      const sel = doc.defaultView?.getSelection?.();
+      if (sel) {
+        sel.removeAllRanges();
+        if (savedRange.current) sel.addRange(savedRange.current);
+        else {
+          const r = doc.createRange();
+          r.selectNodeContents(doc.body);
+          sel.addRange(r);
+        }
+      }
+      const hex = color.startsWith('#') ? color : `#${color}`;
+      doc.execCommand(cmd, false, hex);
+    } catch {
+      /* 命令不可用时静默降级 */
+    }
+  }, []);
+
+  // 句柄：运行时 setValue/getValue/setDisabled/聚焦/切换源码/执行命令。
+  // 须置于 runCommand 定义之后，避免依赖数组访问时触发 TDZ。
+  useImperativeHandle(
+    ref,
+    (): HtmlEditorHandle => ({
+      setValue: (html) => setDynValue(html),
+      getValue: () => {
+        const doc = iframeRef.current?.contentDocument;
+        return doc ? doc.body.innerHTML : '';
+      },
+      setDisabled: (b) => setDynDisabled(b),
+      isDisabled: () => dynDisabled,
+      focus: () => iframeRef.current?.focus(),
+      toggleSource: () => setSourceMode((v) => !v),
+      isSource: () => sourceMode,
+      execCommand: (cmd, val) => runCommand(cmd, val),
+    }),
+    [dynDisabled, sourceMode, runCommand],
+  );
+
+  // 字号增减（对齐 Ext onFontIncrease/onFontDecrease → adjustFont）：维护 1..7 的绝对字号档，
+  // 每次点击在选区上 execCommand('fontsize', N) 放大/缩小一档。Chromium 不支持原生的
+  // increasefontsize/decreasefontsize 命令，故用绝对字号方式达到等价行为。
+  const [fontSize, setFontSize] = React.useState(3);
+  const runFontSize = React.useCallback(
+    (delta: number) => {
+      const next = Math.min(7, Math.max(1, fontSize + delta));
+      setFontSize(next);
+      runCommand('fontsize', String(next));
+    },
+    [fontSize, runCommand],
+  );
+
+  // 插入链接（createlink）：对齐 Ext 默认 createLink 行为——点击按钮弹出 prompt 让用户输入 URL，
+  // 再对当前选区 execCommand('createlink', url)。空输入则不操作。
+  const onLink = React.useCallback(() => {
+    const url = window.prompt('链接地址：', 'http://');
+    if (url) runCommand('createlink', url);
+  }, [runCommand]);
+
+  // 工具栏项：源码编辑按钮带 toggle 态与切换 handler；源码模式下其余按钮禁用
+  // （对齐 Ext toggleSourceEdit 的 disableItems）。格式按钮注入 execCommand handler 与 pressed 态。
+  const items: ToolbarItem[] = React.useMemo(() => {
+    return EDITOR_TOOLBAR.map((it) => {
+      // 字体下拉（x-font-select）：选中后执行 fontname 命令；源码模式下禁用
+      if (React.isValidElement(it) && (it.props as { className?: string }).className === 'x-font-select') {
+        return React.cloneElement(it as React.ReactElement<React.SelectHTMLAttributes<HTMLSelectElement>>, {
+          disabled: sourceMode,
+          onChange: (e: React.ChangeEvent<HTMLSelectElement>) => runCommand('fontname', e.target.value),
+        });
+      }
+      if (React.isValidElement(it) || typeof it !== 'object') return it;
+      const o = it as ToolbarButtonConfig;
+      if (o.iconCls === 'x-edit-sourceedit') {
+        return { ...o, pressed: sourceMode, handler: () => setSourceMode((v) => !v) };
+      }
+      // forecolor/backcolor：点击展开 ColorMenu（调色板），选中颜色后应用命令
+      if (o.iconCls === 'x-edit-forecolor' || o.iconCls === 'x-edit-backcolor') {
+        const cmd = o.iconCls === 'x-edit-forecolor' ? 'forecolor' : 'backcolor';
+        return {
+          ...o,
+          onClick: (e: React.MouseEvent<HTMLButtonElement>) => {
+            const anchor = e.currentTarget as HTMLElement;
+            colorAnchorRef.current = anchor;
+            setColorMenu((prev) => (prev?.cmd === cmd ? null : { cmd, anchor }));
+          },
+        };
+      }
+      if (sourceMode) return { ...o, disabled: true };
+      // 字号增减：点击放大/缩小一档（非 toggle，走 runFontSize 绝对字号）
+      if (o.iconCls === 'x-edit-increasefontsize') {
+        return { ...o, enableToggle: false, handler: () => runFontSize(1) };
+      }
+      if (o.iconCls === 'x-edit-decreasefontsize') {
+        return { ...o, enableToggle: false, handler: () => runFontSize(-1) };
+      }
+      // 插入链接：点击弹出 prompt 取 URL（对齐 Ext createLink）
+      if (o.iconCls === 'x-edit-createlink') {
+        return { ...o, handler: onLink };
+      }
+      const cmd = o.iconCls ? FORMAT_CMD[o.iconCls] : undefined;
+      if (cmd) {
+        return { ...o, pressed: !!formatStates[cmd], handler: () => runCommand(cmd) };
+      }
+      return it;
+    });
+  }, [sourceMode, formatStates, runCommand, runFontSize, onLink]);
+
+  // 源码模式下 textarea 显示 HTML 源码；design 模式为空且隐藏。
+  const srcValue = sourceMode ? dynValue : '';
+
+  return (
+    <div
+      className={['x-form-field-wrap', 'x-html-editor-wrap', className, dynDisabled ? 'x-item-disabled' : '']
+        .filter(Boolean)
+        .join(' ')}
+      data-testid={testId}
+      style={{ width, height, boxSizing: 'border-box', position: 'relative' }}
+    >
+      <div className="x-html-editor-tb">
+        <Toolbar items={items} />
+      </div>
+      <textarea
+        className={`x-form-textarea x-form-field${sourceMode ? '' : ' x-hidden'}`}
+        value={srcValue}
+        readOnly={!sourceMode}
+        style={
+          sourceMode
+            ? {
+                width: iframeW,
+                height: iframeH,
+                position: 'absolute',
+                top: TOOLBAR_H,
+                left: 1,
+                boxSizing: 'border-box',
+                overflow: 'auto',
+                resize: 'none',
+              }
+            : { position: 'absolute', top: -10000, left: -10000, visibility: 'hidden' }
+        }
+      />
+      <iframe
+        ref={iframeRef}
+        title="htmleditor"
+        frameBorder={0}
+        style={{ width: iframeW, height: iframeH, overflow: 'auto', display: sourceMode ? 'none' : undefined }}
+      />
+      {colorMenu && (
+        <ColorMenu
+          open={!!colorMenu}
+          anchorRef={colorAnchorRef}
+          onSelect={(c) => {
+            const hex = c.startsWith('#') ? c : `#${c}`;
+            runColorCommand(colorMenu.cmd, hex);
+            setColorMenu(null);
+          }}
+          onClose={() => setColorMenu(null)}
+        />
+      )}
+    </div>
+  );
+});
+
+(HtmlEditor as React.FC).displayName = 'HtmlEditor';
+
+export default HtmlEditor;