react-extjs 0.0.1

package/src/components/Editor.tsx

@@ -0,0 +1,214 @@
+import React, { forwardRef, useCallback, useEffect, useImperativeHandle, useRef, useState } from 'react';
+
+export interface EditorProps {
+  /** 初始编辑值 */
+  value?: string;
+  /** 编辑框宽度（px），默认 180 */
+  width?: number;
+  /** 编辑框高度（px），默认 22 */
+  height?: number;
+  /** 被编辑元素（boundEl）展示的文本，编辑时隐藏（对齐 Ext.hideEl） */
+  boundText?: string;
+  /** 起始是否处于编辑态（默认 true，便于保真对比与演示） */
+  editing?: boolean;
+  /** 失焦时是否自动完成编辑（对齐 Ext.Editor.allowBlur，默认 true） */
+  allowBlur?: boolean;
+  /** 完成编辑（Enter / 失焦）回调，返回最新值 */
+  onComplete?: (value: string) => void;
+  /** 取消编辑（Esc）回调 */
+  onCancel?: (value: string) => void;
+  /** 根容器附加 className */
+  className?: string;
+}
+
+/**
+ * 复刻 Ext.Editor（行内编辑器）的运行时句柄。
+ *
+ * 命令式方法（通过 ref 调用）：
+ *   startEdit()     进入编辑态（显示浮层并聚焦）
+ *   completeEdit()  提交当前值并退出编辑态（触发 onComplete）
+ *   cancelEdit()    回滚到 startValue 并退出编辑态（触发 onCancel）
+ *   setValue(v)     运行时改写编辑值（同时更新 bound 回显值）
+ *   getValue()      读取当前编辑值
+ *   isEditing()     是否处于编辑态
+ */
+export interface EditorHandle {
+  startEdit: () => void;
+  completeEdit: () => void;
+  cancelEdit: () => void;
+  setValue: (value: string) => void;
+  getValue: () => string;
+  isEditing: () => boolean;
+}
+
+/**
+ * 复刻 Ext.Editor（行内编辑器）。
+ *
+ * DOM 结构（对齐 Ext.Editor.onRender / startEdit）：
+ *   div.x-editor.x-layer                 (浮层，position:absolute，可见)
+ *     div.x-form-field-wrap
+ *       input.x-form-text.x-form-field   (内部 TextField)
+ *
+ * 行为：
+ *   - Enter  → completeEdit（触发 onComplete，隐藏编辑框、恢复 bound 显示）
+ *   - Esc    → cancelEdit（触发 onCancel，值回滚 startValue）
+ *   - 失焦   → 默认 allowBlur 完成编辑
+ *
+ * 注：golden 用 Ext.Editor（shadow:false）渲染到容器并 startEdit 一个 (10,10) 的
+ *     bound 元素，浮层 c-c 对齐后与 react 同尺寸同位置，截图一致。
+ */
+export const Editor = forwardRef<EditorHandle, EditorProps>(function Editor(
+  {
+    value = '',
+    width = 180,
+    height = 22,
+    boundText,
+    editing: editingProp = true,
+    allowBlur = true,
+    onComplete,
+    onCancel,
+    className,
+  },
+  ref,
+) {
+  const [editing, setEditing] = useState(editingProp);
+  const [current, setCurrent] = useState(value);
+  const [startValue] = useState(value);
+  // 最近提交值，用于编辑结束后 bound 文本回显（对齐 Ext.Editor.updateEl）
+  const [committed, setCommitted] = useState(value);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  // refs 镜像最新值，供命令式句柄读取（避免闭包陈旧）
+  const editingRef = useRef(editing);
+  const currentRef = useRef(current);
+  const startValueRef = useRef(startValue);
+
+  // 保持 current 与受控 value 同步
+  useEffect(() => {
+    currentRef.current = value;
+    setCurrent(value);
+    setCommitted(value);
+  }, [value]);
+
+  // 同步 editing 的 state 与 ref（供句柄读取与渲染一致）
+  const syncEditing = useCallback((v: boolean) => {
+    editingRef.current = v;
+    setEditing(v);
+  }, []);
+
+  const completeEdit = useCallback(() => {
+    setCommitted(currentRef.current);
+    syncEditing(false);
+    onComplete?.(currentRef.current);
+  }, [onComplete, syncEditing]);
+
+  const cancelEdit = useCallback(() => {
+    currentRef.current = startValueRef.current;
+    setCurrent(startValueRef.current);
+    setCommitted(startValueRef.current);
+    syncEditing(false);
+    onCancel?.(startValueRef.current);
+  }, [onCancel, syncEditing]);
+
+  const startEdit = useCallback(() => {
+    syncEditing(true);
+  }, [syncEditing]);
+
+  const setValue = useCallback((v: string) => {
+    currentRef.current = v;
+    setCurrent(v);
+    setCommitted(v);
+  }, []);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      startEdit,
+      completeEdit,
+      cancelEdit,
+      setValue,
+      getValue: () => currentRef.current,
+      isEditing: () => editingRef.current,
+    }),
+    [startEdit, completeEdit, cancelEdit, setValue],
+  );
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLInputElement>) => {
+      if (e.key === 'Enter') {
+        e.preventDefault();
+        completeEdit();
+      } else if (e.key === 'Escape') {
+        e.preventDefault();
+        cancelEdit();
+      }
+    },
+    [completeEdit, cancelEdit],
+  );
+
+  const handleBlur = useCallback(() => {
+    // 对齐 Ext.Editor.allowBlur 默认 true：失焦即完成编辑；allowBlur=false 时不自动完成
+    if (allowBlur) completeEdit();
+  }, [allowBlur, completeEdit]);
+
+  // 进入编辑态后聚焦输入框（对齐 Ext.Editor.startEdit 的 focus）
+  useEffect(() => {
+    if (editing && inputRef.current) {
+      inputRef.current.focus();
+    }
+  }, [editing]);
+
+  return (
+    <span
+      className={['x-editor-wrap', className].filter(Boolean).join(' ')}
+      style={{ position: 'relative', display: 'inline-block', width: '100%', height: `${height}px` }}
+    >
+      {boundText !== undefined && (
+        <span
+          className="x-editor-bound"
+          style={{
+            display: editing ? 'none' : 'block',
+            boxSizing: 'border-box',
+            width: '100%',
+            height: `${height}px`,
+            lineHeight: `${height - 4}px`,
+            padding: '2px 3px',
+          }}
+        >
+          {committed}
+        </span>
+      )}
+      {editing && (
+        <div
+          className="x-editor x-layer"
+          style={{
+            position: 'absolute',
+            left: 0,
+            top: 0,
+            width,
+            height,
+            visibility: 'visible',
+            padding: 0,
+            margin: 0,
+          }}
+        >
+          <div className="x-form-field-wrap" style={{ width, height }}>
+            <input
+              ref={inputRef}
+              type="text"
+              className="x-form-text x-form-field"
+              style={{ width: width - 17, height: height - 4 }}
+              value={current}
+              onChange={(e) => {
+                currentRef.current = e.target.value;
+                setCurrent(e.target.value);
+              }}
+              onKeyDown={handleKeyDown}
+              onBlur={handleBlur}
+            />
+          </div>
+        </div>
+      )}
+    </span>
+  );
+});

package/src/components/EditorGrid.tsx

@@ -0,0 +1,361 @@
+import React, {
+  forwardRef,
+  useRef,
+  useState,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  type CSSProperties,
+  type KeyboardEvent,
+  type FocusEvent,
+  type ChangeEvent,
+} from 'react';
+import { Grid, type GridColumn } from './Grid';
+
+export type EditorType = 'text' | 'number';
+
+export interface EditorColumn extends GridColumn {
+  /** 单元格编辑器：true 使用文本编辑器；{ type } 指定 text/number */
+  editor?: boolean | { type?: EditorType };
+}
+
+export interface EditorGridProps {
+  columns: EditorColumn[];
+  data: Record<string, unknown>[];
+  title?: string;
+  width?: number | string;
+  height?: number;
+  stripeRows?: boolean;
+  selectedRow?: number;
+  /** 触发编辑的点击次数，默认 1（单击） */
+  clicksToEdit?: number;
+  className?: string;
+  style?: CSSProperties;
+  /** 提交回调：行索引、字段名、新值 */
+  onCellEdit?: (rowIndex: number, dataIndex: string, value: string) => void;
+  /** 数据源变更回调（对齐 Ext Store 的 datachanged）：任意编辑提交/增删行后触发，参数为最新数据副本 */
+  onDataChange?: (data: Record<string, unknown>[]) => void;
+  /** 行点击事件：参数为被点击行的索引（对齐 Ext Grid 的 rowclick），编辑未开始时触发 */
+  onRowClick?: (rowIndex: number) => void;
+}
+
+/**
+ * 复刻 Ext.EditorGrid 的运行时句柄（动态数据源 / 运行时编辑）。
+ *
+ * 命令式方法（通过 ref 调用）：
+ *   setData(data)        整体替换数据源（双向：兄弟组件或外部状态）
+ *   getData()            读取当前数据源
+ *   addRecord(record)    追加一行
+ *   removeRecord(idx)    按行索引删除一行
+ *   updateRecord(idx,p)  按行索引局部更新字段
+ *   startEditAt(r,col)   运行时按坐标（行索引 + dataIndex）启动单元格编辑
+ *   commitEdit(value?)   提交当前编辑（可选覆盖值）；无编辑态时为 no-op
+ *   cancelEdit()         取消当前编辑并回滚
+ *   isEditing()          是否处于单元格编辑态
+ */
+export interface EditorGridHandle {
+  setData: (data: Record<string, unknown>[]) => void;
+  getData: () => Record<string, unknown>[];
+  addRecord: (record: Record<string, unknown>) => void;
+  removeRecord: (rowIndex: number) => void;
+  updateRecord: (rowIndex: number, patch: Record<string, unknown>) => void;
+  startEditAt: (rowIndex: number, dataIndex: string) => void;
+  commitEdit: (value?: string) => void;
+  cancelEdit: () => void;
+  isEditing: () => boolean;
+}
+
+interface EditingState {
+  rowIndex: number;
+  dataIndex: string;
+  value: string;
+  type: EditorType;
+}
+
+interface Pos {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * 保真映射（来源 src/widgets/grid/EditorGrid.js + Editor.js）：
+ * - EditorGridPanel = GridPanel + EditorGrid 插件；clicksToEdit 默认 1。
+ * - 点击可编辑单元格 → Editor.startEdit(cell, value)：编辑器元素 class 为 x-grid-editor，
+ *   绝对定位覆盖该单元格（top/left/width/height = 单元格盒模型），内含字段（TextField → x-form-field x-form-text）。
+ * - 编辑时单元格文本被隐藏（编辑器覆盖），Enter/失焦提交写回、Esc 取消；提交后触发 afteredit/validateedit。
+ * 复用 Grid 渲染内核，编辑器为覆盖层；DOM/class 与 Ext 3.2.1 一致，复用 ext-all.css。
+ */
+export const EditorGrid = forwardRef<EditorGridHandle, EditorGridProps>(function EditorGrid(
+  {
+    columns,
+    data,
+    title,
+    width,
+    height,
+    stripeRows,
+    selectedRow,
+    clicksToEdit = 1,
+    className,
+    style,
+    onCellEdit,
+    onDataChange,
+    onRowClick,
+  },
+  ref,
+) {
+  const [rows, setRows] = useState<Record<string, unknown>[]>(() => data.map((r) => ({ ...r })));
+  const [editing, setEditing] = useState<EditingState | null>(null);
+  const [pos, setPos] = useState<Pos | null>(null);
+  const [focused, setFocused] = useState(false);
+  const wrapRef = useRef<HTMLDivElement>(null);
+  const cellInnerRef = useRef<HTMLElement | null>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  // 镜像最新数据源供命令式读取（避免闭包陈旧）
+  const rowsRef = useRef(rows);
+  useEffect(() => {
+    rowsRef.current = rows;
+  }, [rows]);
+  // 数据源变更通知（对齐 Ext Store.datachanged）：编辑提交、增删行后触发，
+  // 让外部能拿到最新数据（getData 因闭包时序可能无法同步读取到最新值）。
+  useEffect(() => {
+    onDataChange?.(rows.map((r) => ({ ...r })));
+  }, [rows, onDataChange]);
+
+  useEffect(() => {
+    setRows(data.map((r) => ({ ...r })));
+  }, [data]);
+
+  const closeEdit = useCallback(() => {
+    if (cellInnerRef.current) {
+      cellInnerRef.current.style.visibility = '';
+      cellInnerRef.current = null;
+    }
+    setEditing(null);
+    setPos(null);
+    setFocused(false);
+  }, []);
+
+  const commit = useCallback(
+    (value: string) => {
+      if (!editing) return;
+      const { rowIndex, dataIndex } = editing;
+      setRows((prev) => {
+        const next = prev.map((r) => ({ ...r }));
+        next[rowIndex] = { ...next[rowIndex], [dataIndex]: value };
+        return next;
+      });
+      onCellEdit?.(rowIndex, dataIndex, value);
+      closeEdit();
+    },
+    [editing, onCellEdit, closeEdit],
+  );
+
+  const startEdit = useCallback(
+    (target: HTMLElement) => {
+      const td = target.closest('.x-grid3-cell') as HTMLElement | null;
+      if (!td) return;
+      const tdMatch = td.className.match(/x-grid3-td-([\w-]+)/);
+      if (!tdMatch) return;
+      const dataIndex = tdMatch[1];
+      const col = columns.find((c) => c.dataIndex === dataIndex);
+      if (!col || !col.editor) return; // 不可编辑列直接忽略
+      const rowEl = td.closest('.x-grid3-row') as HTMLElement | null;
+      if (!rowEl || !rowEl.parentElement) return;
+      const rowEls = Array.from(
+        rowEl.parentElement.querySelectorAll(':scope > .x-grid3-row'),
+      ) as HTMLElement[];
+      const rowIndex = rowEls.indexOf(rowEl);
+      if (rowIndex < 0) return;
+      const type: EditorType =
+        typeof col.editor === 'object' ? col.editor.type ?? 'text' : 'text';
+      const value = String(rows[rowIndex]?.[dataIndex] ?? '');
+
+      const wrap = wrapRef.current;
+      if (!wrap) return;
+      const wrapRect = wrap.getBoundingClientRect();
+      const cellRect = td.getBoundingClientRect();
+      setPos({
+        top: cellRect.top - wrapRect.top,
+        left: cellRect.left - wrapRect.left,
+        width: cellRect.width,
+        height: cellRect.height,
+      });
+      setEditing({ rowIndex, dataIndex, value, type });
+      const inner = td.querySelector('.x-grid3-cell-inner') as HTMLElement | null;
+      if (inner) {
+        cellInnerRef.current = inner;
+        inner.style.visibility = 'hidden';
+      }
+    },
+    [columns, rows],
+  );
+
+  const handleClick = useCallback(
+    (e: React.MouseEvent) => {
+      if (editing) return; // 编辑中点击编辑器不重启
+      const tr = (e.target as HTMLElement).closest('.x-grid3-row');
+      if (tr && tr.parentElement) {
+        const rowEls = Array.from(
+          tr.parentElement.querySelectorAll(':scope > .x-grid3-row'),
+        ) as HTMLElement[];
+        const idx = rowEls.indexOf(tr as HTMLElement);
+        if (idx >= 0) onRowClick?.(idx);
+      }
+      startEdit(e.target as HTMLElement);
+    },
+    [editing, startEdit, onRowClick],
+  );
+
+  // 运行时按坐标（行索引 + dataIndex）启动单元格编辑，供命令式句柄调用
+  const startEditAt = useCallback(
+    (rowIndex: number, dataIndex: string) => {
+      const wrap = wrapRef.current;
+      if (!wrap) return;
+      const rowEls = Array.from(
+        wrap.querySelectorAll(':scope .x-grid3-row'),
+      ) as HTMLElement[];
+      const rowEl = rowEls[rowIndex];
+      if (!rowEl) return;
+      const td = rowEl.querySelector(`.x-grid3-td-${dataIndex}`) as HTMLElement | null;
+      if (!td) return;
+      startEdit(td);
+    },
+    [startEdit],
+  );
+
+  // —— 动态数据源句柄 ——
+  const setData = useCallback((next: Record<string, unknown>[]) => {
+    closeEdit();
+    setRows(next.map((r) => ({ ...r })));
+  }, [closeEdit]);
+
+  const getData = useCallback(() => rowsRef.current.map((r) => ({ ...r })), []);
+
+  const addRecord = useCallback((record: Record<string, unknown>) => {
+    setRows((prev) => [...prev, { ...record }]);
+  }, []);
+
+  const removeRecord = useCallback((rowIndex: number) => {
+    setRows((prev) => prev.filter((_, i) => i !== rowIndex));
+  }, []);
+
+  const updateRecord = useCallback((rowIndex: number, patch: Record<string, unknown>) => {
+    setRows((prev) => prev.map((r, i) => (i === rowIndex ? { ...r, ...patch } : r)));
+  }, []);
+
+  const commitEdit = useCallback(
+    (value?: string) => {
+      if (!editing) return;
+      commit(value ?? editing.value);
+    },
+    [editing, commit],
+  );
+
+  const cancelEdit = useCallback(() => {
+    closeEdit();
+  }, [closeEdit]);
+
+  const isEditing = useCallback(() => editing !== null, [editing]);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      setData,
+      getData,
+      addRecord,
+      removeRecord,
+      updateRecord,
+      startEditAt,
+      commitEdit,
+      cancelEdit,
+      isEditing,
+    }),
+    [setData, getData, addRecord, removeRecord, updateRecord, startEditAt, commitEdit, cancelEdit, isEditing],
+  );
+
+  useEffect(() => {
+    if (editing && inputRef.current) {
+      // preventScroll: 阻止浏览器聚焦时自动滚动最近的可滚动祖先（Writer 左 Panel 的
+      // .x-panel-body，overflow:hidden）使编辑器可见——原生 ExtJS 的 .x-grid-editor 渲染在
+      // .x-grid3-scroller 内部，聚焦只滚表体本身、不移动整表；本封装把编辑器浮层放在 scroller
+      // 之外，若放任默认滚动，点击靠右的末列（Last）编辑会让整表左移约 17px 造成抖动。
+      inputRef.current.focus({ preventScroll: true });
+      inputRef.current.select();
+    }
+  }, [editing]);
+
+  const handleKeyDown = (e: KeyboardEvent<HTMLInputElement>) => {
+    if (e.key === 'Enter') {
+      e.preventDefault();
+      commit(e.currentTarget.value);
+    } else if (e.key === 'Escape') {
+      e.preventDefault();
+      closeEdit();
+    }
+  };
+
+  const handleChange = (e: ChangeEvent<HTMLInputElement>) => {
+    setEditing((prev) => (prev ? { ...prev, value: e.target.value } : prev));
+  };
+
+  const handleBlur = (e: FocusEvent<HTMLInputElement>) => {
+    setFocused(false);
+    if (editing) commit(e.currentTarget.value);
+  };
+
+  return (
+    <div
+      ref={wrapRef}
+      className={className}
+      style={{ position: 'relative', ...(style as CSSProperties) }}
+      onClick={clicksToEdit === 1 ? handleClick : undefined}
+      onDoubleClick={clicksToEdit === 2 ? handleClick : undefined}
+    >
+      <Grid
+        columns={columns}
+        data={rows}
+        title={title}
+        width={width}
+        height={height}
+        stripeRows={stripeRows}
+        selectedRow={selectedRow}
+      />
+      {editing && pos && (
+        <div
+          className="x-grid-editor"
+          style={{
+            position: 'absolute',
+            zIndex: 50,
+            top: pos.top,
+            left: pos.left,
+            width: pos.width,
+            height: pos.height,
+          }}
+        >
+          <input
+            ref={inputRef}
+            type={editing.type === 'number' ? 'number' : 'text'}
+            className={[
+              'x-form-field',
+              editing.type === 'number' ? 'x-form-num-field x-form-text' : 'x-form-text',
+              focused ? 'x-form-focus' : '',
+            ]
+              .filter(Boolean)
+              .join(' ')}
+            value={editing.value}
+            style={{ width: '100%', height: '100%', boxSizing: 'border-box' }}
+            onFocus={() => setFocused(true)}
+            onBlur={handleBlur}
+            onChange={handleChange}
+            onKeyDown={handleKeyDown}
+          />
+        </div>
+      )}
+    </div>
+  );
+});
+
+export default EditorGrid;

package/src/components/FieldLabeler.tsx

@@ -0,0 +1,81 @@
+import React from 'react';
+import { TextField } from './Form';
+
+/**
+ * 保真 Ext.ux.FieldLabeler（一个挂载到字段上的 plugin）。
+ *
+ * 作用：无论字段身处何种容器布局，都在渲染时给字段套上标准 Ext 表单的
+ * 「x-form-item + x-form-item-label」包裹并渲染 label，等价于 FormLayout 的效果。
+ *
+ * React 中以包裹组件表达：外层 x-form-label-{align}（祖先，供 ext-all.css 的
+ * left/top/right 规则命中）→ 内层 x-form-item → label.x-form-item-label + x-form-element。
+ * label 宽度 / 对齐 / 分隔符 / 内边距均对齐 Ext 默认值（100 / left / ":" / 5）。
+ */
+
+export interface FieldLabelerProps {
+  /** 被包裹的字段组件，默认 TextField（对齐 Ext 任意 Field 可挂 plugin） */
+  as?: React.ComponentType<any>;
+  /** 传给被包裹字段的共享 props（name / width / placeholder / data 等） */
+  fieldProps?: Record<string, any>;
+  /** label 文案（对齐 Ext fieldLabel，必填） */
+  fieldLabel: string;
+  /** label 对齐方式，默认 'left'（对齐 Ext labelAlign） */
+  labelAlign?: 'left' | 'right' | 'top';
+  /** label 宽度（px），默认 100（对齐 Ext labelWidth） */
+  labelWidth?: number;
+  /** label 分隔符，默认 ':'（对齐 Ext labelSeparator） */
+  labelSeparator?: string;
+  /** label 与字段的水平内边距（px），默认 5（对齐 Ext labelPad） */
+  labelPad?: number;
+  /** 隐藏 label（对齐 Ext hideLabels） */
+  hideLabel?: boolean;
+  id?: string;
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+export const FieldLabeler: React.FC<FieldLabelerProps> = ({
+  as: FieldComp = TextField,
+  fieldProps = {},
+  fieldLabel,
+  labelAlign = 'left',
+  labelWidth = 100,
+  labelSeparator = ':',
+  labelPad = 5,
+  hideLabel = false,
+  id,
+  className,
+  style,
+}) => {
+  const showLabel = !hideLabel;
+  // 非 top 且显示 label 时，字段区需让出 label 宽度（对齐 Ext resizeEl.setStyle('padding-left')）
+  const elementStyle: React.CSSProperties =
+    labelAlign === 'top' || !showLabel
+      ? { paddingLeft: 0 }
+      : { paddingLeft: labelWidth + labelPad };
+
+  return (
+    <div
+      id={id}
+      className={['x-form-label-' + labelAlign, className].filter(Boolean).join(' ')}
+      style={style}
+    >
+      <div className="x-form-item">
+        {showLabel && (
+          <label
+            className="x-form-item-label"
+            style={labelAlign === 'top' ? undefined : { width: labelWidth }}
+          >
+            {fieldLabel}
+            {labelSeparator}
+          </label>
+        )}
+        <div className="x-form-element" style={elementStyle}>
+          <FieldComp {...fieldProps} />
+        </div>
+      </div>
+    </div>
+  );
+};
+
+FieldLabeler.displayName = 'FieldLabeler';