react-extjs 0.0.1

package/src/components/Form.tsx

@@ -0,0 +1,3484 @@
+/**
+ * Ext.form.* 保真复刻（来源 src/widgets/form + src/widgets/layout/FormLayout.js）
+ *
+ * 保真契约：
+ * - FormLayout.fieldTpl（217-223 行）：x-form-item > label.x-form-item-label + div.x-form-element
+ * - Field.onRender：input 带 x-form-field x-form-{type}（type=text → x-form-text）
+ * - Checkbox.onRender：x-form-check-wrap > input.x-form-checkbox + label.x-form-cb-label
+ * - TriggerField.onRender：x-form-field-wrap x-form-field-trigger-wrap > input.x-form-text + img.x-form-trigger
+ * React 仅重写行为与状态，DOM/class 与 Ext JS 3.2.1 一致，复用 ext-all.css 得到像素级还原。
+ */
+import { useState, useCallback, useEffect, useRef, useMemo, useLayoutEffect, useImperativeHandle, forwardRef, cloneElement, Children, isValidElement, Fragment, type ReactElement, type ReactNode, type CSSProperties } from 'react';
+import { createPortal } from 'react-dom';
+import { Panel } from './Panel';
+
+// 浮层 portal 目标：必须位于 React 根容器 DOM 子树内。
+// 原因：React 18 把事件委托监听器挂在根容器上；若把下拉/日历浮层 createPortal 到
+// document.body（根容器的兄弟节点），原生点击事件冒泡到 body 时并不经过根容器，
+// 导致浮层内选项的 React onClick 永远不触发、下拉「无法选择」。
+// 列表本身使用 position:fixed 视口定位，挂在内层覆盖 div 不会被 overflow 裁剪。
+let __portalRoot: HTMLElement | null = null;
+function getPortalRoot(): HTMLElement {
+  if (__portalRoot && document.body.contains(__portalRoot)) return __portalRoot;
+  const host = document.getElementById('docs-root') || document.getElementById('root') || document.body;
+  const el = document.createElement('div');
+  el.className = 'x-portal-root';
+  host.appendChild(el);
+  __portalRoot = el;
+  return el;
+}
+import { DatePicker } from './DatePicker';
+import { Button } from './Button';
+
+const BLANK_IMG = '/extjs-assets/images/default/s.gif';
+
+/* ------------------------------------------------------------------ */
+/* FormField —— 复刻 FormLayout.fieldTpl 的字段包裹结构                */
+/* ------------------------------------------------------------------ */
+export interface FormFieldProps {
+  id?: string;
+  fieldLabel?: ReactNode;
+  labelAlign?: 'left' | 'top' | 'right';
+  labelWidth?: number;
+  labelPad?: number;
+  labelSeparator?: string;
+  hideLabel?: boolean;
+  itemCls?: string;
+  children?: ReactNode;
+  style?: CSSProperties;
+}
+
+export function FormField({
+  id,
+  fieldLabel,
+  labelAlign = 'left',
+  labelWidth = 100,
+  labelPad = 5,
+  labelSeparator = ':',
+  hideLabel,
+  itemCls = '',
+  children,
+  style,
+}: FormFieldProps) {
+  const isTop = labelAlign === 'top';
+  const labelStyle: CSSProperties = isTop
+    ? { width: 'auto' }
+    : { width: `${labelWidth}px` };
+  const elementStyle: CSSProperties = isTop
+    ? { paddingLeft: 0 }
+    : { paddingLeft: `${labelWidth + labelPad}px` };
+
+  const itemClass = [
+    'x-form-item',
+    itemCls,
+    hideLabel ? 'x-hide-label' : '',
+    `x-form-label-${labelAlign}`,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  // 把 id 透传给唯一子输入（Ext 中 field.id 落在 input 上，label htmlFor 才能关联）
+  const child = Children.count(children) === 1 ? (Children.toArray(children)[0] as ReactElement) : null;
+  const childWithId =
+    id && child && child.props && (child.props as { id?: string }).id === undefined
+      ? cloneElement(child, { id })
+      : children;
+
+  return (
+    <div className={itemClass} tabIndex={-1} style={style}>
+      {!hideLabel && fieldLabel != null && (
+        <label htmlFor={id} style={labelStyle} className="x-form-item-label">
+          {fieldLabel}
+          {labelSeparator}
+        </label>
+      )}
+      <div className="x-form-element" id={id ? `x-form-el-${id}` : undefined} style={elementStyle}>
+        {childWithId}
+      </div>
+      <div className="x-form-clear-left"></div>
+    </div>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/* 输入类字段基类（text / number 共用）                                */
+/* ------------------------------------------------------------------ */
+/** 校验相关配置（对齐 Ext.form.Field 的 allowBlank / validator / invalidText / msgTarget） */
+export interface FieldValidationProps {
+  /** 是否允许为空，默认 true。false 时空值即无效。 */
+  allowBlank?: boolean;
+  /** allowBlank=false 时空值报错文案。 */
+  /** 自定义校验：返回 true 表示通过；返回字符串表示错误信息（该字符串即为错误提示）。 */
+  validator?: (value: string) => boolean | string;
+  /** 默认错误提示（allowBlank=false 时空值使用，或被 validator 返回的 true 之外的情况兜底）。 */
+  invalidText?: string;
+  /** 错误展示位置：'side'（字段右侧红色感叹号图标，默认）/ 'under'（字段下方红色文字）。 */
+  msgTarget?: 'side' | 'under';
+  /** 失焦时是否自动校验，默认 true（对齐 Ext Field 默认行为）。 */
+  validateOnBlur?: boolean;
+  /** 最小输入长度（默认 0）。 */
+  minLength?: number;
+  /** 最大输入长度（默认 524288，仅校验不硬性截断）。 */
+  maxLength?: number;
+  /** 最小长度校验失败文案（{0} 替换为阈值）。 */
+  minLengthText?: string;
+  /** 最大长度校验失败文案（{0} 替换为阈值）。 */
+  maxLengthText?: string;
+  /** 自定义正则，失败报 regexText。 */
+  regex?: RegExp;
+  /** 正则校验失败文案。 */
+  regexText?: string;
+  /** 内置校验类型 email / url / alpha / alphanum（对齐 Ext VTypes）。 */
+  vtype?: 'email' | 'url' | 'alpha' | 'alphanum';
+  /** 覆盖 vtype 默认错误文案。 */
+  vtypeText?: string;
+  /** 按键过滤正则，不匹配字符被拦截（对齐 Ext maskRe）。 */
+  maskRe?: RegExp;
+  /** 输入后剔除字符正则（对齐 Ext stripCharsRe）。 */
+  stripCharsRe?: RegExp;
+  /** 聚焦时全选文本（对齐 Ext selectOnFocus，默认 false）。 */
+  selectOnFocus?: boolean;
+  /** 随内容自动增长宽度（对齐 Ext grow，默认 false）。 */
+  grow?: boolean;
+  /** grow 时最小宽度（默认 30）。 */
+  growMin?: number;
+  /** grow 时最大宽度（默认 800）。 */
+  growMax?: number;
+}
+
+/** 通过 ref 暴露的命令式校验接口（对齐 Ext form.Field.validate / clearInvalid / reset / setValue / selectText 等）。 */
+export interface TextFieldHandle {
+  /** 执行校验：更新无效态并返回是否通过。 */
+  validate: () => boolean;
+  /** 清除无效态。 */
+  clearInvalid: () => void;
+  /** 当前是否已通过校验（不更新错误态）。 */
+  isValid: () => boolean;
+  /** 重置为初始值并清除错误态（对齐 Ext reset）。 */
+  reset: () => void;
+  /** 设置值（对齐 Ext setValue，并触发 onChange）。 */
+  setValue: (v: string) => void;
+  /** 获取当前值（对齐 Ext getValue）。 */
+  getValue: () => string;
+  /** 选中文本 start..end（对齐 Ext selectText）。 */
+  selectText: (start?: number, end?: number) => void;
+  /** 聚焦输入框。 */
+  focus: () => void;
+}
+
+interface BaseInputProps extends FieldValidationProps {
+  id?: string;
+  name?: string;
+  value?: string;
+  defaultValue?: string;
+  emptyText?: string;
+  disabled?: boolean;
+  readOnly?: boolean;
+  width?: number;
+  cls?: string;
+  inputType?: string;
+  style?: CSSProperties;
+  onChange?: (value: string) => void;
+  onFocus?: () => void;
+  onBlur?: () => void;
+}
+
+function useFieldValue(initial?: string, defaultValue?: string) {
+  const [value, setValue] = useState(initial ?? defaultValue ?? '');
+  return [value, setValue] as const;
+}
+
+/** 内置 VTypes（对齐 Ext.form.VTypes 的 email / url / alpha / alphanum）。 */
+const VTYPES: Record<string, { re: RegExp; text: string }> = {
+  email: {
+    re: /^([\w]+)([-+.][\w]+)*@([\w-]+\.)+[a-zA-Z]{2,7}$/,
+    text: 'This field should be an e-mail address in the format "user@domain.com"',
+  },
+  url: {
+    re: /(((^https?)|(^ftp)):\/\/(((\w+\.)?)+)?(\w*)((:(\d+))?)(\/([\w#!:.?+=&%@!\-\/])?)?)/i,
+    text: 'This field should be a URL in the format "http:/' + '/www.domain.com"',
+  },
+  alpha: { re: /^[a-zA-Z_]+$/, text: 'This field should only contain letters and _' },
+  alphanum: { re: /^[a-zA-Z0-9_]+$/, text: 'This field should only contain letters, numbers and _' },
+};
+
+/** 依据当前值计算错误文案（null 表示通过）。对齐 Ext Field.getErrors / TextField.getErrors 的校验链路。 */
+export function computeError(
+  value: string,
+  opts: FieldValidationProps,
+): string | null {
+  const v = value ?? '';
+  const isEmpty = v.length < 1;
+
+  if (typeof opts.validator === 'function') {
+    const r = opts.validator(v);
+    if (r !== true) return typeof r === 'string' ? r : opts.invalidText ?? '输入值无效';
+  }
+  if (isEmpty) {
+    if (opts.allowBlank === false) return opts.invalidText ?? '该输入为必填项';
+    return null;
+  }
+  if (typeof opts.minLength === 'number' && v.length < opts.minLength) {
+    return (opts.minLengthText ?? 'The minimum length for this field is {0}').replace(
+      '{0}',
+      String(opts.minLength),
+    );
+  }
+  if (typeof opts.maxLength === 'number' && v.length > opts.maxLength) {
+    return (opts.maxLengthText ?? 'The maximum length for this field is {0}').replace(
+      '{0}',
+      String(opts.maxLength),
+    );
+  }
+  if (opts.vtype && VTYPES[opts.vtype] && !VTYPES[opts.vtype].re.test(v)) {
+    return opts.vtypeText ?? VTYPES[opts.vtype].text;
+  }
+  if (opts.regex && !opts.regex.test(v)) {
+    return opts.regexText ?? '输入值格式不正确';
+  }
+  return null;
+}
+
+const TextInput = forwardRef<TextFieldHandle, BaseInputProps & { elementClass: string }>(
+  function TextInput(
+    {
+      id,
+      name,
+      value,
+      defaultValue,
+      emptyText,
+      disabled,
+      readOnly,
+      width,
+      cls = '',
+      inputType = 'text',
+      elementClass,
+      style,
+      onChange,
+      onFocus,
+      onBlur,
+      allowBlank,
+      validator,
+      invalidText,
+      msgTarget = 'side',
+      validateOnBlur = true,
+      minLength,
+      maxLength,
+      minLengthText,
+      maxLengthText,
+      regex,
+      regexText,
+      vtype,
+      vtypeText,
+      maskRe,
+      stripCharsRe,
+      selectOnFocus = false,
+      grow = false,
+      growMin = 30,
+      growMax = 800,
+    },
+    ref,
+  ) {
+    const [focused, setFocused] = useState(false);
+    const [internal, setInternal] = useFieldValue(value, defaultValue);
+    const [error, setError] = useState<string | null>(null);
+    const current = value !== undefined ? value : internal;
+    const inputRef = useRef<HTMLInputElement>(null);
+    const iconRef = useRef<HTMLDivElement>(null);
+    const initialRef = useRef<string>(value ?? defaultValue ?? '');
+
+    const validationOpts: FieldValidationProps = {
+      allowBlank,
+      validator,
+      invalidText,
+      minLength,
+      maxLength,
+      minLengthText,
+      maxLengthText,
+      regex,
+      regexText,
+      vtype,
+      vtypeText,
+    };
+
+    const validate = useCallback((): boolean => {
+      const e = computeError(current, validationOpts);
+      setError(e);
+      return e === null;
+    }, [current, validationOpts]); // eslint-disable-line react-hooks/exhaustive-deps
+
+    useImperativeHandle(
+      ref,
+      () => ({
+        validate,
+        clearInvalid: () => setError(null),
+        isValid: () => computeError(current, validationOpts) === null,
+        reset: () => {
+          setInternal(initialRef.current);
+          setError(null);
+        },
+        setValue: (v: string) => {
+          if (value === undefined) setInternal(v);
+          onChange?.(v);
+        },
+        getValue: () => current,
+        selectText: (start = 0, end = current.length) => {
+          const el = inputRef.current;
+          if (!el) return;
+          el.focus();
+          try {
+            el.setSelectionRange(start, end);
+          } catch {
+            /* IE 分支省略 */
+          }
+        },
+        focus: () => inputRef.current?.focus(),
+      }),
+      [validate, current, validationOpts, value, onChange], // eslint-disable-line react-hooks/exhaustive-deps
+    );
+
+    // 已标红时，值变化即时重校验（编辑中清除/刷新错误，对齐 Ext 字段校验联动行为）。
+    useEffect(() => {
+      setError((prev) => (prev === null ? prev : computeError(current, validationOpts)));
+    }, [current, validationOpts]); // eslint-disable-line react-hooks/exhaustive-deps
+
+    // side 模式：感叹号图标需定位到 input 右缘 +2（对齐 Ext alignErrorIcon 的 tl-tr [2,0]）。
+    useLayoutEffect(() => {
+      if (error && msgTarget === 'side' && inputRef.current && iconRef.current) {
+        const inp = inputRef.current;
+        iconRef.current.style.left = `${inp.offsetLeft + inp.offsetWidth + 2}px`;
+        iconRef.current.style.top = `${inp.offsetTop}px`;
+      }
+    }, [error, msgTarget, current]);
+
+    const isEmpty = current.length === 0;
+    const inputClass = [
+      'x-form-field',
+      elementClass,
+      cls,
+      focused ? 'x-form-focus' : '',
+      !focused && isEmpty && emptyText ? 'x-form-empty-field' : '',
+      error ? 'x-form-invalid' : '',
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    // grow：随内容调整宽度（对齐 Ext grow / growMin / growMax）
+    let effWidth = width;
+    if (grow) {
+      effWidth = Math.min(growMax, Math.max((current.length || 1) * 7 + 12, growMin));
+    }
+
+    const handleFocus = useCallback(() => {
+      setFocused(true);
+      if (selectOnFocus && inputRef.current) inputRef.current.select();
+      onFocus?.();
+    }, [selectOnFocus, onFocus]);
+
+    const handleBlur = useCallback(() => {
+      setFocused(false);
+      onBlur?.();
+      if (validateOnBlur) validate();
+    }, [onBlur, validateOnBlur, validate]);
+
+    const handleKeyDown = useCallback(
+      (e: React.KeyboardEvent<HTMLInputElement>) => {
+        if (maskRe && e.key.length === 1 && !maskRe.test(e.key)) {
+          e.preventDefault();
+        }
+      },
+      [maskRe],
+    );
+
+    const handleChange = useCallback(
+      (e: React.ChangeEvent<HTMLInputElement>) => {
+        let v = e.target.value;
+        if (stripCharsRe) v = v.replace(stripCharsRe, '');
+        if (value === undefined) setInternal(v);
+        onChange?.(v);
+      },
+      [value, onChange, stripCharsRe],
+    );
+
+    return (
+      <>
+        <input
+          ref={inputRef}
+          id={id}
+          name={name}
+          type={inputType}
+          className={inputClass}
+          value={current}
+          placeholder={emptyText}
+          disabled={disabled}
+          readOnly={readOnly}
+          style={{ height: 22, ...(effWidth !== undefined ? { width: effWidth } : {}), ...style }}
+          onFocus={handleFocus}
+          onBlur={handleBlur}
+          onKeyDown={handleKeyDown}
+          onChange={handleChange}
+        />
+        {error && msgTarget === 'side' && (
+          <div
+            ref={iconRef}
+            className="x-form-invalid-icon"
+            title={error}
+            style={{ visibility: 'visible' }}
+          />
+        )}
+        {error && msgTarget === 'under' && (
+          <div className="x-form-invalid-msg" style={{ display: 'block' }}>
+            {error}
+          </div>
+        )}
+      </>
+    );
+  },
+);
+
+export interface TextFieldProps extends BaseInputProps {}
+export const TextField = forwardRef<TextFieldHandle, TextFieldProps>((props, ref) => (
+  <TextInput ref={ref} {...props} elementClass="x-form-text" />
+));
+
+export interface NumberFieldProps extends Omit<BaseInputProps, 'inputType'> {
+  /** 是否允许小数（默认 true）。false 时拦截并剔除小数点。 */
+  allowDecimals?: boolean;
+  /** 小数分隔符（默认 '.'）。 */
+  decimalSeparator?: string;
+  /** 显示小数位精度（默认 2，-1 表示不限制）。失焦时按此精度四舍五入。 */
+  decimalPrecision?: number;
+  /** 是否允许负号（默认 true）。false 时拦截并剔除 '-'。 */
+  allowNegative?: boolean;
+  /** 最小值（默认 -Infinity）。 */
+  minValue?: number;
+  /** 最大值（默认 +Infinity）。 */
+  maxValue?: number;
+  /** 小于最小值时报文（{0} 替换为阈值）。 */
+  minText?: string;
+  /** 大于最大值时报文（{0} 替换为阈值）。 */
+  maxText?: string;
+  /** 非有效数字时报文（{0} 替换为原输入）。 */
+  nanText?: string;
+  /** allowBlank=false 时空值报错文案。 */
+  blankText?: string;
+  /** 合法字符基集（默认 '0123456789'）。与 decimalSeparator / '-'（若允许）共同构成自动 maskRe。 */
+  baseChars?: string;
+}
+
+/** 数值字段校验：解析失败 / 越界 / 必填空值 / 自定义 validator，返回错误文案或 null。 */
+function computeNumberError(
+  raw: string,
+  o: {
+    allowBlank?: boolean;
+    blankText?: string;
+    validator?: (v: string) => boolean | string;
+    invalidText?: string;
+    minValue: number;
+    maxValue: number;
+    minText?: string;
+    maxText?: string;
+    nanText?: string;
+    decimalSeparator: string;
+  },
+): string | null {
+  const v = (raw ?? '').trim();
+  if (o.allowBlank === false && v === '') {
+    return o.blankText ?? '该输入为必填项';
+  }
+  if (v === '') return null;
+  const num = parseFloat(v.replace(o.decimalSeparator, '.'));
+  if (isNaN(num)) {
+    return (o.nanText ?? '{0} 不是有效数字').replace('{0}', v);
+  }
+  if (num < o.minValue) {
+    return (o.minText ?? '最小值为 {0}').replace('{0}', String(o.minValue));
+  }
+  if (num > o.maxValue) {
+    return (o.maxText ?? '最大值为 {0}').replace('{0}', String(o.maxValue));
+  }
+  if (o.validator) {
+    const r = o.validator(v);
+    if (r !== true) return typeof r === 'string' ? r : o.invalidText ?? '输入值无效';
+  }
+  return null;
+}
+
+/** 按 decimalPrecision 四舍五入修正显示值（对齐 Ext fixPrecision + setValue）。 */
+function fixPrecision(
+  raw: string,
+  allowDecimals: boolean,
+  decimalPrecision: number,
+  decimalSeparator: string,
+): string {
+  if (!allowDecimals || decimalPrecision === -1 || raw.trim() === '') return raw;
+  const num = parseFloat(raw.replace(decimalSeparator, '.'));
+  if (isNaN(num)) return raw;
+  const fixed = parseFloat(num.toFixed(decimalPrecision));
+  return String(fixed).replace('.', decimalSeparator);
+}
+
+export const NumberField = forwardRef<TextFieldHandle, NumberFieldProps>((props, ref) => {
+  const {
+    allowDecimals = true,
+    decimalSeparator = '.',
+    decimalPrecision = 2,
+    allowNegative = true,
+    minValue = Number.NEGATIVE_INFINITY,
+    maxValue = Number.MAX_VALUE,
+    minText,
+    maxText,
+    nanText,
+    baseChars = '0123456789',
+    allowBlank,
+    validator,
+    invalidText,
+    blankText,
+    maskRe,
+    msgTarget = 'side',
+    validateOnBlur = true,
+  } = props;
+  const [focused, setFocused] = useState(false);
+  const [internal, setInternal] = useFieldValue(props.value, props.defaultValue);
+  const [error, setError] = useState<string | null>(null);
+  const current = props.value !== undefined ? props.value : internal;
+  const inputRef = useRef<HTMLInputElement>(null);
+  const iconRef = useRef<HTMLDivElement>(null);
+  const initialRef = useRef<string>(props.value ?? props.defaultValue ?? '');
+
+  const vProps = {
+    allowBlank,
+    blankText,
+    validator,
+    invalidText,
+    minValue,
+    maxValue,
+    minText,
+    maxText,
+    nanText,
+    decimalSeparator,
+  };
+
+  const validate = useCallback((): boolean => {
+    const e = computeNumberError(current, vProps);
+    setError(e);
+    return e === null;
+  }, [current, allowBlank, blankText, validator, invalidText, minValue, maxValue, minText, maxText, nanText, decimalSeparator]);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      validate,
+      clearInvalid: () => setError(null),
+      isValid: () => computeNumberError(current, vProps) === null,
+      reset: () => {
+        setInternal(initialRef.current);
+        setError(null);
+      },
+      setValue: (v: string) => {
+        const fixed = fixPrecision(v, allowDecimals, decimalPrecision, decimalSeparator);
+        if (props.value === undefined) setInternal(fixed);
+        props.onChange?.(fixed);
+      },
+      getValue: () => current,
+      selectText: (start = 0, end = current.length) => {
+        const el = inputRef.current;
+        if (!el) return;
+        el.focus();
+        try {
+          el.setSelectionRange(start, end);
+        } catch {
+          /* IE 分支省略 */
+        }
+      },
+      focus: () => inputRef.current?.focus(),
+    }),
+    [validate, current, props.value, props.onChange, allowBlank, blankText, validator, invalidText, minValue, maxValue, minText, maxText, nanText, decimalSeparator, allowDecimals, decimalPrecision],
+  );
+
+  // 已标红时值变化即时重校验（对齐 Ext 字段校验联动）。
+  useEffect(() => {
+    setError((prev) => (prev === null ? prev : computeNumberError(current, vProps)));
+  }, [current, allowBlank, blankText, validator, invalidText, minValue, maxValue, minText, maxText, nanText, decimalSeparator]);
+
+  // side 模式：感叹号图标定位到 input 右缘。
+  useLayoutEffect(() => {
+    if (error && msgTarget === 'side' && inputRef.current && iconRef.current) {
+      const inp = inputRef.current;
+      iconRef.current.style.left = `${inp.offsetLeft + inp.offsetWidth + 2}px`;
+      iconRef.current.style.top = `${inp.offsetTop}px`;
+    }
+  }, [error, msgTarget, current]);
+
+  // 自动 maskRe：baseChars + 小数分隔符 + '-'(若允许)。可被显式 maskRe 覆盖。
+  const autoMask = useMemo(() => {
+    if (maskRe) return maskRe;
+    let chars = baseChars;
+    if (allowDecimals) chars += decimalSeparator;
+    if (allowNegative) chars += '-';
+    const escaped = chars.replace(/[\\[\]^-]/g, '\\$&');
+    return new RegExp(`[${escaped}]`);
+  }, [maskRe, baseChars, allowDecimals, decimalSeparator, allowNegative]);
+
+  const inputClass = [
+    'x-form-field',
+    'x-form-num-field',
+    'x-form-text',
+    props.cls,
+    focused ? 'x-form-focus' : '',
+    !focused && current.length === 0 && props.emptyText ? 'x-form-empty-field' : '',
+    error ? 'x-form-invalid' : '',
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  const handleFocus = useCallback(() => setFocused(true), []);
+  const handleBlur = useCallback(() => {
+    setFocused(false);
+    // 失焦时按精度修正显示值（对齐 Ext setValue 的 fixPrecision）。受控/非受控都要修正。
+    const fixed = fixPrecision(current, allowDecimals, decimalPrecision, decimalSeparator);
+    if (fixed !== current) {
+      if (props.value === undefined) setInternal(fixed);
+      else props.onChange?.(fixed);
+    }
+    if (validateOnBlur) validate();
+  }, [current, props.value, props.onChange, allowDecimals, decimalPrecision, decimalSeparator, validateOnBlur, validate]);
+
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+    if (autoMask && e.key.length === 1 && !autoMask.test(e.key)) {
+      e.preventDefault();
+    }
+  };
+
+  const handleChange = useCallback(
+    (e: React.ChangeEvent<HTMLInputElement>) => {
+      let v = e.target.value;
+      // 录入时强制剔除不符合的数值字符（兜底粘贴场景）。
+      if (!allowNegative) v = v.replace(/-/g, '');
+      if (!allowDecimals) {
+        const idx = v.indexOf(decimalSeparator);
+        if (idx !== -1) v = v.slice(0, idx);
+      }
+      if (props.value === undefined) setInternal(v);
+      props.onChange?.(v);
+    },
+    [props.value, props.onChange, allowNegative, allowDecimals, decimalSeparator],
+  );
+
+  return (
+    <>
+      <input
+        ref={inputRef}
+        id={props.id}
+        name={props.name}
+        type="text"
+        inputMode="decimal"
+        className={inputClass}
+        value={current}
+        placeholder={props.emptyText}
+        disabled={props.disabled}
+        readOnly={props.readOnly}
+        style={{ height: 22, ...(props.width ? { width: props.width } : {}), ...props.style }}
+        onFocus={handleFocus}
+        onBlur={handleBlur}
+        onKeyDown={handleKeyDown}
+        onChange={handleChange}
+      />
+      {error && msgTarget === 'side' && (
+        <div
+          ref={iconRef}
+          className="x-form-invalid-icon"
+          title={error}
+          style={{ visibility: 'visible' }}
+        />
+      )}
+      {error && msgTarget === 'under' && (
+        <div className="x-form-invalid-msg" style={{ display: 'block' }}>
+          {error}
+        </div>
+      )}
+    </>
+  );
+});
+
+export { TextInput };
+
+export interface TextAreaProps extends Omit<BaseInputProps, 'inputType'> {
+  /** 可见行数（默认 4）。 */
+  rows?: number;
+  /** 随内容自动增长高度（对齐 Ext grow，默认 false）。 */
+  grow?: boolean;
+  /** grow 时最小高度（默认 60）。 */
+  growMin?: number;
+  /** grow 时最大高度（默认 1000）。 */
+  growMax?: number;
+  /** true 时禁止滚动条（配合 grow 相当于 overflow:hidden，默认 false）。 */
+  preventScrollbars?: boolean;
+  /** 回车是否视为特殊键（Ext enterIsSpecial，默认 false；本复刻仅作为属性保留以对齐 API）。 */
+  enterIsSpecial?: boolean;
+}
+export const TextArea = forwardRef<TextFieldHandle, TextAreaProps>((props, ref) => {
+  const {
+    rows = 4,
+    grow = false,
+    growMin = 60,
+    growMax = 1000,
+    preventScrollbars = false,
+    allowBlank,
+    validator,
+    invalidText,
+    minLength,
+    maxLength,
+    minLengthText,
+    maxLengthText,
+    regex,
+    regexText,
+    vtype,
+    vtypeText,
+    maskRe,
+    stripCharsRe,
+    selectOnFocus = false,
+    msgTarget = 'side',
+    validateOnBlur = true,
+  } = props;
+  const [focused, setFocused] = useState(false);
+  const [internal, setInternal] = useFieldValue(props.value, props.defaultValue);
+  const [error, setError] = useState<string | null>(null);
+  const current = props.value !== undefined ? props.value : internal;
+  const taRef = useRef<HTMLTextAreaElement>(null);
+  const iconRef = useRef<HTMLDivElement>(null);
+  const initialRef = useRef<string>(props.value ?? props.defaultValue ?? '');
+
+  const vProps = {
+    allowBlank,
+    validator,
+    invalidText,
+    minLength,
+    maxLength,
+    minLengthText,
+    maxLengthText,
+    regex,
+    regexText,
+    vtype,
+    vtypeText,
+  };
+
+  const validate = useCallback((): boolean => {
+    const e = computeError(current, vProps);
+    setError(e);
+    return e === null;
+  }, [current, allowBlank, validator, invalidText, minLength, maxLength, minLengthText, maxLengthText, regex, regexText, vtype, vtypeText]);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      validate,
+      clearInvalid: () => setError(null),
+      isValid: () => computeError(current, vProps) === null,
+      reset: () => {
+        setInternal(initialRef.current);
+        setError(null);
+      },
+      setValue: (v: string) => {
+        if (props.value === undefined) setInternal(v);
+        props.onChange?.(v);
+      },
+      getValue: () => current,
+      selectText: (start = 0, end = current.length) => {
+        const el = taRef.current;
+        if (!el) return;
+        el.focus();
+        try {
+          el.setSelectionRange(start, end);
+        } catch {
+          /* IE 分支省略 */
+        }
+      },
+      focus: () => taRef.current?.focus(),
+    }),
+    [validate, current, props.value, props.onChange, allowBlank, validator, invalidText, minLength, maxLength, minLengthText, maxLengthText, regex, regexText, vtype, vtypeText],
+  );
+
+  const inputClass = [
+    'x-form-field',
+    'x-form-text',
+    'x-form-textarea',
+    props.cls,
+    focused ? 'x-form-focus' : '',
+    !focused && current.length === 0 && props.emptyText ? 'x-form-empty-field' : '',
+    error ? 'x-form-invalid' : '',
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  // 已标红时，值变化即时重校验（对齐 Ext 字段校验联动行为）。
+  useEffect(() => {
+    setError((prev) => (prev === null ? prev : computeError(current, vProps)));
+  }, [current, allowBlank, validator, invalidText, minLength, maxLength, minLengthText, maxLengthText, regex, regexText, vtype, vtypeText]);
+
+  // grow：随内容自动调整高度，范围为 [growMin, growMax]。
+  useLayoutEffect(() => {
+    if (!grow || !taRef.current) return;
+    const el = taRef.current;
+    el.style.height = 'auto';
+    const h = Math.min(Math.max(el.scrollHeight, growMin), growMax);
+    el.style.height = `${h}px`;
+  }, [grow, growMin, growMax, current, focused]);
+
+  // side 模式：感叹号图标定位到 textarea 右缘。
+  useLayoutEffect(() => {
+    if (error && msgTarget === 'side' && taRef.current && iconRef.current) {
+      const el = taRef.current;
+      iconRef.current.style.left = `${el.offsetLeft + el.offsetWidth + 2}px`;
+      iconRef.current.style.top = `${el.offsetTop}px`;
+    }
+  }, [error, msgTarget, current]);
+
+  const handleFocus = useCallback(() => {
+    setFocused(true);
+    if (selectOnFocus && taRef.current) {
+      const el = taRef.current;
+      el.focus();
+      try {
+        el.setSelectionRange(0, el.value.length);
+      } catch {
+        /* IE 分支省略 */
+      }
+    }
+  }, [selectOnFocus]);
+
+  const handleBlur = useCallback(() => {
+    setFocused(false);
+    if (validateOnBlur) validate();
+  }, [validateOnBlur, validate]);
+
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    if (maskRe && e.key.length === 1 && !maskRe.test(e.key)) {
+      e.preventDefault();
+    }
+  };
+
+  const handleChange = useCallback(
+    (e: React.ChangeEvent<HTMLTextAreaElement>) => {
+      let v = e.target.value;
+      if (stripCharsRe) v = v.replace(stripCharsRe, '');
+      if (props.value === undefined) setInternal(v);
+      props.onChange?.(v);
+    },
+    [props.value, props.onChange, stripCharsRe],
+  );
+
+  return (
+    <>
+      <textarea
+        ref={taRef}
+        id={props.id}
+        name={props.name}
+        className={inputClass}
+        rows={rows}
+        value={current}
+        placeholder={props.emptyText}
+        disabled={props.disabled}
+        readOnly={props.readOnly}
+        style={{
+          ...(grow ? { height: growMin } : { height: 60 }),
+          ...(props.width ? { width: props.width } : {}),
+          ...(preventScrollbars ? { overflow: 'hidden' } : {}),
+        }}
+        onFocus={handleFocus}
+        onBlur={handleBlur}
+        onKeyDown={handleKeyDown}
+        onChange={handleChange}
+      />
+      {error && msgTarget === 'side' && (
+        <div
+          ref={iconRef}
+          className="x-form-invalid-icon"
+          title={error}
+          style={{ visibility: 'visible' }}
+        />
+      )}
+      {error && msgTarget === 'under' && (
+        <div className="x-form-invalid-msg" style={{ display: 'block' }}>
+          {error}
+        </div>
+      )}
+    </>
+  );
+});
+
+/* ------------------------------------------------------------------ */
+/* Checkbox —— 复刻 Checkbox.onRender 的 x-form-check-wrap            */
+/* ------------------------------------------------------------------ */
+/** 命令式句柄（对齐 Ext.form.Checkbox 的 getValue / setValue / toggle / focus）。 */
+export interface CheckboxHandle {
+  /** 获取勾选态（对齐 Ext Checkbox.getValue，返回 boolean）。 */
+  getValue: () => boolean;
+  /** 设置勾选态：传 boolean 直接设定；传 inputValue 字符串时匹配即选（对齐 Ext setValue 接受原始值）。 */
+  setValue: (v: boolean | string) => void;
+  /** 切换勾选态（对齐 Ext Checkbox.toggle）。 */
+  toggle: () => void;
+  /** 聚焦选项框。 */
+  focus: () => void;
+}
+
+export interface CheckboxProps {
+  id?: string;
+  name?: string;
+  /** 选框右侧文字（对齐 Ext boxLabel），与 htmlFor 关联点击切换。 */
+  boxLabel?: ReactNode;
+  /** 提交时的值（对齐 Ext inputValue，默认 'on'）；仅勾选时随表单提交该值。 */
+  inputValue?: string;
+  /** 受控勾选态。提供时作为唯一来源（受控模式）。 */
+  checked?: boolean;
+  /** 非受控初始勾选态（默认 false）。 */
+  defaultChecked?: boolean;
+  /** 禁用（对齐 Ext disabled，整组 x-item-disabled 置灰）。 */
+  disabled?: boolean;
+  /** 勾选态变化回调，返回当前是否勾选。 */
+  onChange?: (checked: boolean) => void;
+  /** 附加 class（追加到 x-form-check-wrap 之后）。 */
+  cls?: string;
+  /** 根 span 行内样式。 */
+  style?: CSSProperties;
+}
+
+export const Checkbox = forwardRef<CheckboxHandle, CheckboxProps>(function Checkbox(
+  {
+    id,
+    name,
+    boxLabel,
+    inputValue = 'on',
+    checked,
+    defaultChecked,
+    disabled,
+    onChange,
+    cls = '',
+    style,
+  },
+  ref,
+) {
+  const [internal, setInternal] = useState(checked ?? defaultChecked ?? false);
+  const isChecked = checked !== undefined ? checked : internal;
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  const setChecked = useCallback(
+    (v: boolean) => {
+      if (checked === undefined) setInternal(v);
+      onChange?.(v);
+    },
+    [checked, onChange],
+  );
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      getValue: () => (checked !== undefined ? checked : internal),
+      setValue: (v: boolean | string) => setChecked(v === true || v === inputValue),
+      toggle: () =>
+        setChecked(!(checked !== undefined ? checked : internal)),
+      focus: () => inputRef.current?.focus(),
+    }),
+    [checked, internal, inputValue, setChecked],
+  );
+
+  const wrapClass = ['x-form-check-wrap', disabled ? 'x-item-disabled' : '', cls]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <span className={wrapClass} style={style}>
+      <input
+        ref={inputRef}
+        id={id}
+        name={name}
+        type="checkbox"
+        className="x-form-field x-form-checkbox"
+        value={inputValue}
+        checked={isChecked}
+        disabled={disabled}
+        onChange={(e) => setChecked(e.target.checked)}
+      />
+      {boxLabel != null && (
+        <label htmlFor={id} className="x-form-cb-label">
+          {boxLabel}
+        </label>
+      )}
+    </span>
+  );
+});
+Checkbox.displayName = 'Checkbox';
+
+/* ------------------------------------------------------------------ */
+/* Radio —— 复刻 Radio.js（继承 Checkbox，inputType=radio）          */
+/* onRender：x-form-check-wrap > input.x-form-field.x-form-radio      */
+/*          + label.x-form-cb-label（boxLabel）                       */
+/* ------------------------------------------------------------------ */
+export interface RadioProps {
+  id?: string;
+  name?: string;
+  boxLabel?: ReactNode;
+  inputValue?: string;
+  checked?: boolean;
+  defaultChecked?: boolean;
+  disabled?: boolean;
+  cls?: string;
+  style?: CSSProperties;
+  onChange?: (checked: boolean) => void;
+}
+export interface RadioHandle {
+  getValue: () => boolean;
+  setValue: (v: boolean | string) => void;
+  toggle: () => void;
+  focus: () => void;
+}
+export const Radio = forwardRef<RadioHandle, RadioProps>(function Radio(
+  {
+    id,
+    name,
+    boxLabel,
+    inputValue,
+    checked,
+    defaultChecked,
+    disabled,
+    cls,
+    style,
+    onChange,
+  },
+  ref
+) {
+  const [internal, setInternal] = useState(checked ?? defaultChecked ?? false);
+  const isChecked = checked !== undefined ? checked : internal;
+
+  const inputRef = useRef<HTMLInputElement>(null);
+  // 跟踪最新勾选态，供命令式句柄读取（对齐 Ext getValue）。
+  const checkedRef = useRef(isChecked);
+  checkedRef.current = isChecked;
+
+  const apply = (v: boolean) => {
+    if (checked === undefined) setInternal(v);
+    onChange?.(v);
+  };
+
+  useImperativeHandle(ref, () => ({
+    getValue: () => checkedRef.current,
+    setValue: (v) => {
+      if (typeof v === 'string') {
+        const on = v === inputValue;
+        apply(on);
+      } else {
+        apply(v);
+      }
+    },
+    toggle: () => apply(!checkedRef.current),
+    focus: () => inputRef.current?.focus(),
+  }));
+
+  return (
+    <span
+      className={['x-form-check-wrap', disabled ? 'x-item-disabled' : '', cls]
+        .filter(Boolean)
+        .join(' ')}
+      style={style}
+    >
+      <input
+        ref={inputRef}
+        id={id}
+        name={name}
+        type="radio"
+        className="x-form-field x-form-radio"
+        value={inputValue}
+        checked={isChecked}
+        disabled={disabled}
+        onChange={(e) => {
+          const v = e.target.checked;
+          if (checked === undefined) setInternal(v);
+          // 受控（如 RadioGroup）场景下，onChange 已由上层替换为携带 inputValue 的回调，
+          // 这里统一回调即可触发组协调（互斥取消其他项）。
+          onChange?.(v);
+        }}
+      />
+      {boxLabel != null && (
+        <label htmlFor={id} className="x-form-cb-label">
+          {boxLabel}
+        </label>
+      )}
+    </span>
+  );
+});
+Radio.displayName = 'Radio';
+
+export interface RadioGroupProps {
+  name?: string;
+  value?: string;
+  defaultValue?: string;
+  fieldLabel?: ReactNode;
+  labelAlign?: 'left' | 'top' | 'right';
+  labelWidth?: number;
+  labelPad?: number;
+  labelSeparator?: string;
+  hideLabel?: boolean;
+  /** 列数（对齐 Ext RadioGroup.columns）：>1 时按多列横向排布，默认 1（竖向堆叠） */
+  columns?: number;
+  /** 是否竖向堆叠（对齐 Ext RadioGroup.vertical）；默认 false（columns=1 时仍竖向，columns>1 时不生效） */
+  vertical?: boolean;
+  /** 组内内容区宽度（对齐 Ext field width）；不传则按内容自适应，与其它表单字段对齐时显式传入 */
+  width?: number;
+  style?: React.CSSProperties;
+  className?: string;
+  children?: ReactNode;
+  onChange?: (value: string) => void;
+}
+export interface RadioGroupHandle {
+  /** 获取当前选中项的 inputValue（对齐 Ext RadioGroup.getValue） */
+  getValue: () => string | undefined;
+  /** 程序化选中某项（对齐 Ext RadioGroup.setValue） */
+  setValue: (v: string) => void;
+}
+/**
+ * RadioGroup —— 复刻 Ext.form.RadioGroup 的包裹容器 x-form-radio-group。
+ * 通过受控组 value 协调组内单选（同名 + 互斥），组内 Radio 用相同 name 由浏览器原生分组。
+ * 支持 columns / vertical 布局（对齐 Ext.columns / vertical），并暴露 getValue / setValue 命令句柄。
+ */
+export const RadioGroup = forwardRef<RadioGroupHandle, RadioGroupProps>(function RadioGroup(
+  {
+    name,
+    value,
+    defaultValue,
+    fieldLabel,
+    labelAlign = 'left',
+    labelWidth = 100,
+    labelPad = 5,
+    labelSeparator = ':',
+    hideLabel,
+    columns,
+    vertical,
+    width,
+    style,
+    className,
+    children,
+    onChange,
+  },
+  ref
+) {
+  // 初值优先级：受控 value > 组 defaultValue > 子 Radio 的 defaultChecked 推导。
+  const [internal, setInternal] = useState<string | undefined>(() => {
+    if (value !== undefined) return value;
+    if (defaultValue !== undefined) return defaultValue;
+    let initial: string | undefined;
+    Children.forEach(children, (child) => {
+      if (!isValidElement(child)) return;
+      const c = child as ReactElement<{ defaultChecked?: boolean; inputValue?: string }>;
+      if (c.props.defaultChecked) initial = c.props.inputValue;
+    });
+    return initial;
+  });
+  const current = value !== undefined ? value : internal;
+  const currentRef = useRef(current);
+  currentRef.current = current;
+
+  useImperativeHandle(ref, () => ({
+    getValue: () => currentRef.current,
+    setValue: (v) => {
+      if (value === undefined) setInternal(v);
+      onChange?.(v);
+    },
+  }));
+
+  const items = Children.map(children, (child) => {
+    if (!isValidElement(child)) return child;
+    const c = child as ReactElement<{ name?: string; inputValue?: string; checked?: boolean; onChange?: (v: boolean) => void }>;
+    const childName = c.props.name ?? name;
+    const childValue = c.props.inputValue;
+    return cloneElement(c, {
+      name: childName,
+      checked: current === childValue,
+      onChange: () => {
+        if (value === undefined) setInternal(childValue);
+        onChange?.(childValue as string);
+      },
+    } as Partial<typeof c.props>);
+  });
+
+  // 布局对齐 Ext：RadioGroup 默认横向单行（vertical 默认 false）；
+  // vertical=true 才竖向堆叠；columns>1 时横向多列网格（忽略 vertical）。
+  const cols = typeof columns === 'number' && columns > 1 ? columns : 1;
+  const horizontal = !vertical;
+  const groupStyle: CSSProperties = {
+    ...(horizontal
+      ? { display: 'flex', flexWrap: cols > 1 ? 'wrap' : 'nowrap', gap: 8, alignItems: 'center' }
+      : { display: 'flex', flexDirection: 'column', gap: 6 }),
+    ...(width != null ? { width } : {}),
+    ...style,
+  };
+
+  const isTop = labelAlign === 'top';
+  const labelStyle: CSSProperties = isTop ? { width: 'auto' } : { width: `${labelWidth}px` };
+  const itemClass = ['x-form-item', `x-form-label-${labelAlign}`]
+    .filter(Boolean)
+    .join(' ');
+  return (
+    <div className={[itemClass, className].filter(Boolean).join(' ')} tabIndex={-1}>
+      {!hideLabel && fieldLabel != null && (
+        <label style={labelStyle} className="x-form-item-label">
+          {fieldLabel}
+          {labelSeparator}
+        </label>
+      )}
+      <div
+        className="x-form-element"
+        style={isTop ? { paddingLeft: 0 } : { paddingLeft: `${labelWidth + labelPad}px` }}
+      >
+        <div className="x-form-radio-group" style={groupStyle}>
+          {cols > 1
+            ? items?.map((it, i) => (
+                <div key={i} style={{ width: `calc(${100 / cols}% - 8px)` }}>
+                  {it}
+                </div>
+              ))
+            : items}
+        </div>
+      </div>
+      <div className="x-form-clear-left"></div>
+    </div>
+  );
+});
+RadioGroup.displayName = 'RadioGroup';
+
+/* ------------------------------------------------------------------ */
+/* Hidden —— 复刻 Ext.form.Hidden（input type=hidden，无可见 UI）     */
+/* ------------------------------------------------------------------ */
+export interface HiddenProps {
+  name?: string;
+  value?: string;
+}
+/** 命令式句柄：对齐 Ext.form.Hidden 的 getValue / setValue */
+export interface HiddenHandle {
+  getValue: () => string;
+  setValue: (v: string) => void;
+}
+export const Hidden = forwardRef<HiddenHandle, HiddenProps>(
+  ({ name, value }, ref) => {
+    const inputRef = useRef<HTMLInputElement>(null);
+    const [internal, setInternal] = useState(value ?? '');
+    const current = value !== undefined ? value : internal;
+
+    useImperativeHandle(ref, () => ({
+      getValue: () => (value !== undefined ? value : (inputRef.current?.value ?? internal)),
+      setValue: (v: string) => {
+        if (inputRef.current) inputRef.current.value = v;
+        if (value === undefined) setInternal(v);
+      },
+    }));
+
+    return <input ref={inputRef} type="hidden" name={name} className="x-hidden" value={current} />;
+  },
+);
+Hidden.displayName = 'Hidden';
+
+/* ------------------------------------------------------------------ */
+/* TriggerField —— 复刻 Ext.form.TriggerField（文本 + 触发器基类）   */
+/* onRender：span.x-form-field-wrap.x-form-field-trigger-wrap        */
+/*          > input.x-form-text + img.x-form-trigger(可加 triggerClass)*/
+/* 点击触发器触发 onTriggerClick（对齐 Ext onTriggerClick）；本身不含   */
+/* 下拉，下拉类（ComboBox/DateField）在其上扩展。                     */
+/* ------------------------------------------------------------------ */
+export interface TriggerFieldProps {
+  id?: string;
+  name?: string;
+  value?: string;
+  width?: number;
+  editable?: boolean;
+  disabled?: boolean;
+  /** 附加在触发器 img 上的 class（对齐 Ext triggerClass），用于自定义图标 */
+  triggerClass?: string;
+  /** 隐藏触发器（对齐 Ext hideTrigger） */
+  hideTrigger?: boolean;
+  emptyText?: string;
+  placeholder?: string;
+  /** 点击触发器回调（对齐 Ext onTriggerClick） */
+  onTriggerClick?: () => void;
+  onChange?: (value: string) => void;
+  cls?: string;
+  style?: React.CSSProperties;
+}
+/** 命令式句柄：对齐 Ext.form.TriggerField 的 getValue / setValue / focus */
+export interface TriggerFieldHandle {
+  getValue: () => string;
+  setValue: (v: string) => void;
+  focus: () => void;
+}
+export const TriggerField = forwardRef<TriggerFieldHandle, TriggerFieldProps>(
+  (
+    {
+      id,
+      name,
+      value,
+      width,
+      editable = true,
+      disabled,
+      triggerClass,
+      hideTrigger,
+      emptyText,
+      placeholder,
+      onTriggerClick,
+      onChange,
+      cls,
+      style,
+    },
+    ref,
+  ) => {
+    const [internal, setInternal] = useState(value ?? '');
+    const current = value !== undefined ? value : internal;
+    const [focused, setFocused] = useState(false);
+    const [triggerOver, setTriggerOver] = useState(false);
+    const inputRef = useRef<HTMLInputElement>(null);
+
+    useImperativeHandle(ref, () => ({
+      getValue: () => (value !== undefined ? value : (inputRef.current?.value ?? internal)),
+      setValue: (v: string) => {
+        if (inputRef.current) inputRef.current.value = v;
+        if (value === undefined) setInternal(v);
+        onChange?.(v);
+      },
+      focus: () => inputRef.current?.focus(),
+    }));
+
+    const wrapClass = [
+      'x-form-field-wrap',
+      'x-form-field-trigger-wrap',
+      focused ? 'x-trigger-wrap-focus' : '',
+      cls ?? '',
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    const TRIGGER_W = 17;
+
+    return (
+      <span style={{ position: 'relative', display: 'inline-block', width: width ?? undefined, ...style }}>
+        <span
+          className={wrapClass}
+          style={{ display: 'block', width: '100%', position: 'relative' }}
+        >
+          <input
+            ref={inputRef}
+            id={id}
+            name={name}
+            type="text"
+            className="x-form-field x-form-text"
+            value={current}
+            readOnly={!editable}
+            disabled={disabled}
+            placeholder={placeholder ?? emptyText}
+            style={{
+              height: 22,
+              width: hideTrigger ? '100%' : `calc(100% - ${TRIGGER_W}px)`,
+              boxSizing: 'border-box',
+            }}
+            onFocus={() => setFocused(true)}
+            onBlur={() => setFocused(false)}
+            onChange={(e) => {
+              if (value === undefined) setInternal(e.target.value);
+              onChange?.(e.target.value);
+            }}
+          />
+          {!hideTrigger && (
+            <img
+              className={[
+                'x-form-trigger',
+                triggerClass ?? '',
+                triggerOver ? 'x-form-trigger-over' : '',
+              ]
+                .filter(Boolean)
+                .join(' ')}
+              src={BLANK_IMG}
+              alt=""
+              role="button"
+              style={{ position: 'absolute', right: 0, top: 0, width: TRIGGER_W, height: 22 }}
+              onMouseEnter={() => setTriggerOver(true)}
+              onMouseLeave={() => setTriggerOver(false)}
+              onClick={() => !disabled && onTriggerClick?.()}
+            />
+          )}
+        </span>
+      </span>
+    );
+  },
+);
+TriggerField.displayName = 'TriggerField';
+
+/* ------------------------------------------------------------------ */
+/* SearchField —— 复刻 Ext.ux.form.SearchField（TwinTriggerField 子类） */
+/* onRender：span.x-form-field-wrap.x-form-field-trigger-wrap          */
+/*          > input.x-form-text + span.x-form-twin-triggers            */
+/*              > img.x-form-trigger.x-form-clear-trigger(默认隐藏)     */
+/*              > img.x-form-trigger.x-form-search-trigger              */
+/* 行为对齐 Ext：Enter / 点搜索触发 onTrigger2Click；清除键在搜索后显示， */
+/* 点清除触发 onTrigger1Click（清空值、隐藏清除键）。store 的 reload 在    */
+/* React 中以 onSearch / onClear 回调取代。                            */
+/* ------------------------------------------------------------------ */
+export interface SearchFieldProps {
+  id?: string;
+  name?: string;
+  value?: string;
+  /** 字段宽度（对齐 Ext width，默认 180） */
+  width?: number;
+  disabled?: boolean;
+  /** 只读（不可编辑，对齐 Ext editable:false） */
+  editable?: boolean;
+  emptyText?: string;
+  placeholder?: string;
+  /** 参数名（对齐 Ext paramName，仅作语义保留） */
+  paramName?: string;
+  /** 点击搜索触发（对齐 Ext onTrigger2Click 的 store.reload 行为） */
+  onSearch?: (query: string) => void;
+  /** 点击清除触发（对齐 Ext onTrigger1Click） */
+  onClear?: () => void;
+  onChange?: (value: string) => void;
+  cls?: string;
+  style?: CSSProperties;
+}
+/** 命令式句柄：对齐 TriggerField.getValue / setValue / focus，外加 clear/reset */
+export interface SearchFieldHandle {
+  getValue: () => string;
+  setValue: (v: string) => void;
+  reset: () => void;
+  clear: () => void;
+  focus: () => void;
+}
+export const SearchField = forwardRef<SearchFieldHandle, SearchFieldProps>(
+  (
+    {
+      id,
+      name,
+      value,
+      width = 180,
+      disabled,
+      editable = true,
+      emptyText,
+      placeholder,
+      paramName = 'query',
+      onSearch,
+      onClear,
+      onChange,
+      cls,
+      style,
+    },
+    ref,
+  ) => {
+    const isControlled = value !== undefined;
+    const [internal, setInternal] = useState(value ?? '');
+    const current = isControlled ? value! : internal;
+    const [focused, setFocused] = useState(false);
+    const [hasSearch, setHasSearch] = useState(false);
+    const [over1, setOver1] = useState(false); // 清除 trigger
+    const [over2, setOver2] = useState(false); // 搜索 trigger
+    const inputRef = useRef<HTMLInputElement>(null);
+
+    const setRaw = (v: string) => {
+      if (!isControlled) setInternal(v);
+      onChange?.(v);
+    };
+
+    // 对齐 Ext onTrigger2Click（搜索）
+    const onSearchClick = () => {
+      if (current.length < 1) {
+        onClearClick();
+        return;
+      }
+      onSearch?.(current);
+      setHasSearch(true);
+    };
+
+    // 对齐 Ext onTrigger1Click（清除）
+    const onClearClick = () => {
+      if (!hasSearch) return;
+      if (inputRef.current) inputRef.current.value = '';
+      setRaw('');
+      onClear?.();
+      setHasSearch(false);
+    };
+
+    useImperativeHandle(ref, () => ({
+      getValue: () => (isControlled ? (inputRef.current?.value ?? current) : (inputRef.current?.value ?? internal)),
+      setValue: (v: string) => {
+        if (inputRef.current) inputRef.current.value = v;
+        setRaw(v);
+      },
+      reset: () => {
+        if (inputRef.current) inputRef.current.value = '';
+        setRaw('');
+        setHasSearch(false);
+        onClear?.();
+      },
+      clear: () => {
+        if (inputRef.current) inputRef.current.value = '';
+        setRaw('');
+        setHasSearch(false);
+        onClear?.();
+      },
+      focus: () => inputRef.current?.focus(),
+    }));
+
+    const wrapClass = [
+      'x-form-field-wrap',
+      'x-form-field-trigger-wrap',
+      'x-form-twin-triggers-wrap',
+      focused ? 'x-trigger-wrap-focus' : '',
+      cls ?? '',
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    return (
+      <span style={{ position: 'relative', display: 'inline-block', width, ...style }}>
+        <span
+          className={wrapClass}
+          style={{ display: 'flex', alignItems: 'stretch', width: '100%', position: 'relative' }}
+        >
+          <input
+            ref={inputRef}
+            id={id}
+            name={name}
+            data-param-name={paramName}
+            type="text"
+            className="x-form-field x-form-text"
+            value={current}
+            readOnly={!editable}
+            disabled={disabled}
+            placeholder={placeholder ?? emptyText}
+            style={{
+              flex: '1 1 auto',
+              minWidth: 0,
+              height: 22,
+              boxSizing: 'border-box',
+            }}
+            onFocus={() => setFocused(true)}
+            onBlur={() => setFocused(false)}
+            onKeyDown={(e) => {
+              if (e.key === 'Enter') {
+                e.preventDefault();
+                onSearchClick();
+              }
+            }}
+            onChange={(e) => setRaw(e.target.value)}
+          />
+          <span className="x-form-twin-triggers" style={{ display: 'flex', flex: '0 0 auto' }}>
+            <img
+              className={['x-form-trigger', 'x-form-clear-trigger', over1 ? 'x-form-trigger-over' : ''].filter(Boolean).join(' ')}
+              src={BLANK_IMG}
+              alt=""
+              role="button"
+              style={hasSearch ? { flex: '0 0 auto' } : { display: 'none' }}
+              onMouseEnter={() => setOver1(true)}
+              onMouseLeave={() => setOver1(false)}
+              onClick={() => !disabled && onClearClick()}
+            />
+            <img
+              className={['x-form-trigger', 'x-form-search-trigger', over2 ? 'x-form-trigger-over' : ''].filter(Boolean).join(' ')}
+              src={BLANK_IMG}
+              alt=""
+              role="button"
+              style={{ flex: '0 0 auto' }}
+              onMouseEnter={() => setOver2(true)}
+              onMouseLeave={() => setOver2(false)}
+              onClick={() => !disabled && onSearchClick()}
+            />
+          </span>
+        </span>
+      </span>
+    );
+  },
+);
+SearchField.displayName = 'SearchField';
+
+/* ------------------------------------------------------------------ */
+/* FileUploadField —— 复刻 Ext.ux.form.FileUploadField（TextField + 文件按钮）*/
+/* onRender：span.x-form-field-wrap.x-form-file-wrap                       */
+/*   > input.x-form-text.x-form-file-text（只读，显示文件名，z-index:3）     */
+/*   > span.x-form-file-btn（绝对定位右侧，z-index:1）                      */
+/*       > Ext.Button（"Browse..."）                                       */
+/*       > input.x-form-file[type=file]（透明覆盖按钮，z-index:2，触发系统对话框）*/
+/* buttonOnly 隐藏文本框、wrap 收为按钮宽；fileselected 事件 -> onFileSelected。*/
+/* ------------------------------------------------------------------ */
+export interface FileUploadFieldProps {
+  id?: string;
+  name?: string;
+  /** 受控显示值（文件名）。不提供时由内部状态管理（选中文件后写入文件名）。 */
+  value?: string;
+  width?: number;
+  disabled?: boolean;
+  /** 按钮文字（对齐 Ext buttonText，默认 'Browse...'） */
+  buttonText?: string;
+  /** 仅显示按钮、隐藏文本框（对齐 Ext buttonOnly，默认 false） */
+  buttonOnly?: boolean;
+  /** 按钮与文本框间距像素（对齐 Ext buttonOffset，默认 3） */
+  buttonOffset?: number;
+  /** 对齐 Ext buttonCfg：可覆盖按钮文字 / 图标 class / 附加 class */
+  buttonCfg?: { text?: string; iconCls?: string; cls?: string };
+  /** 占位提示（未选择文件时） */
+  emptyText?: string;
+  /** file input 的 accept 过滤（HTML 原生，扩展项） */
+  accept?: string;
+  /** 是否允许多选（HTML 原生，扩展项） */
+  multiple?: boolean;
+  /** 内容变化回调（文件名） */
+  onChange?: (value: string) => void;
+  /** 对齐 Ext fileselected 事件：选中文件后回调（value, file） */
+  onFileSelected?: (value: string, file?: File) => void;
+  cls?: string;
+  style?: React.CSSProperties;
+}
+/** 命令式句柄：对齐 Ext.ux.form.FileUploadField 的 getValue / setValue 与文件读取 */
+export interface FileUploadFieldHandle {
+  getValue: () => string;
+  setValue: (v: string) => void;
+  getFile: () => File | null;
+  reset: () => void;
+  focus: () => void;
+}
+export const FileUploadField = forwardRef<FileUploadFieldHandle, FileUploadFieldProps>(
+  (
+    {
+      id,
+      name,
+      value,
+      width,
+      disabled,
+      buttonText = 'Browse...',
+      buttonOnly = false,
+      buttonOffset = 8,
+      buttonCfg,
+      emptyText,
+      accept,
+      multiple,
+      onChange,
+      onFileSelected,
+      cls,
+      style,
+    },
+    ref,
+  ) => {
+    const wrapW = width ?? 220;
+    const btnText = buttonCfg?.text ?? buttonText;
+    const [internal, setInternal] = useState(value ?? '');
+    const current = value !== undefined ? value : internal;
+    const [file, setFile] = useState<File | null>(null);
+    const [focused, setFocused] = useState(false);
+    const [btnW, setBtnW] = useState(0);
+    const [resetKey, setResetKey] = useState(0);
+    const btnRef = useRef<HTMLSpanElement>(null);
+    const textRef = useRef<HTMLInputElement>(null);
+
+    useImperativeHandle(ref, () => ({
+      getValue: () => (value !== undefined ? value : internal),
+      setValue: (v: string) => {
+        if (value === undefined) setInternal(v);
+        onChange?.(v);
+      },
+      getFile: () => file,
+      reset: () => {
+        setFile(null);
+        if (value === undefined) setInternal('');
+        setResetKey((k) => k + 1);
+        onChange?.('');
+      },
+      focus: () => textRef.current?.focus(),
+    }));
+
+    // 测量按钮宽度，作为文本框右边界（对齐 Ext onResize：text 宽 = wrap - button - offset）。
+    // useLayoutEffect 在绘制前提交，无可见闪烁。
+    useLayoutEffect(() => {
+      if (btnRef.current) setBtnW(btnRef.current.offsetWidth);
+    }, [btnText, buttonOnly]);
+
+    const wrapClass = [
+      'x-form-field-wrap',
+      'x-form-file-wrap',
+      focused ? 'x-trigger-wrap-focus' : '',
+      disabled ? 'x-item-disabled' : '',
+      cls ?? '',
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    const textWidth = Math.max(0, wrapW - btnW - buttonOffset);
+
+    return (
+      <span style={{ position: 'relative', display: 'inline-block', ...style }}>
+        <span
+          className={wrapClass}
+          style={{
+            display: 'inline-block',
+            width: buttonOnly && btnW ? btnW : wrapW,
+            height: 22,
+          }}
+        >
+          {!buttonOnly && (
+            <input
+              ref={textRef}
+              id={id}
+              type="text"
+              className="x-form-field x-form-text x-form-file-text"
+              value={current}
+              readOnly
+              disabled={disabled}
+              placeholder={emptyText}
+              style={{ position: 'absolute', left: 0, top: 0, zIndex: 3, height: 22, width: textWidth }}
+              onFocus={() => setFocused(true)}
+              onBlur={() => setFocused(false)}
+            />
+          )}
+          <span
+            ref={btnRef}
+            className={['x-form-file-btn', buttonCfg?.cls ?? ''].filter(Boolean).join(' ')}
+            style={{ position: 'absolute', right: 0, top: 0, zIndex: 1 }}
+          >
+            <Button text={btnText} scale="small" disabled={disabled} iconCls={buttonCfg?.iconCls} />
+            <input
+              key={resetKey}
+              type="file"
+              name={name || id}
+              className="x-form-file"
+              accept={accept}
+              multiple={multiple}
+              disabled={disabled}
+              style={{
+                position: 'absolute',
+                inset: 0,
+                width: '100%',
+                height: '100%',
+                zIndex: 2,
+                opacity: 0,
+                cursor: disabled ? 'default' : 'pointer',
+                fontSize: 0,
+                color: 'transparent',
+              }}
+              onChange={(e) => {
+                const f = e.target.files?.[0];
+                const v = f ? f.name : '';
+                if (value === undefined) setInternal(v);
+                setFile(f ?? null);
+                if (v) {
+                  onChange?.(v);
+                  onFileSelected?.(v, f);
+                }
+              }}
+            />
+          </span>
+        </span>
+      </span>
+    );
+  },
+);
+FileUploadField.displayName = 'FileUploadField';
+
+/* ------------------------------------------------------------------ */
+/* MultiSelect —— 复刻 Ext.ux.form.MultiSelect（FieldSet + 多选列表）*/
+/* onRender：fieldset.x-fieldset(.x-multiselect)                        */
+/*   > legend.x-fieldset-header（legend 标题）                          */
+/*   > div.x-fieldset-bwrap                                            */
+/*       (可选 tbar 工具栏)                                            */
+/*       > div.x-fieldset-body.ux-mselect（多选列表，对齐 Ext ListView）*/
+/* 选择逻辑对齐 Ext.ListView multiSelect：单击替换、ctrl 加选/减选、   */
+/* shift 范围选；getValue 返回 delimiter 分隔串、getRawValue 返回数组。  */
+/* ------------------------------------------------------------------ */
+export interface MultiSelectDataItem {
+  value: string;
+  text: string;
+}
+/** 数据源归一化输入：string[] | [value,text][] | {value,text}[] */
+export type MultiSelectData = Array<string | number | Array<string | number> | { value?: string | number; text?: string }>;
+export interface MultiSelectProps {
+  id?: string;
+  name?: string;
+  /** 控件宽度（像素），对齐 Ext width（默认 200，比 Ext 默认 100 更实用） */
+  width?: number;
+  /** 列表可视高度（像素），对齐 Ext height（默认 100） */
+  height?: number;
+  /** 对齐 Ext legend：用 fieldset 包裹并显示标题 */
+  legend?: string;
+  /** 数据源：string[] / [value,text][] / {value,text}[] */
+  data?: MultiSelectData;
+  /** 受控值：delimiter 分隔字符串或数组；不提供时内部状态管理 */
+  value?: string | string[];
+  /** 值分隔符（对齐 Ext delimiter，默认 ','） */
+  delimiter?: string;
+  disabled?: boolean;
+  /** 是否允许空选（对齐 Ext allowBlank，默认 true） */
+  allowBlank?: boolean;
+  /** 最少选中项数（对齐 Ext minSelections，默认 0） */
+  minSelections?: number;
+  /** 最多选中项数（对齐 Ext maxSelections，默认 Number.MAX_VALUE） */
+  maxSelections?: number;
+  /** 顶部工具栏：简化的按钮配置数组（对齐 Ext tbar） */
+  tbar?: Array<{ text: string; onClick?: () => void; disabled?: boolean }>;
+  cls?: string;
+  style?: CSSProperties;
+  /** 选中变化回调（回传选中 value 数组，对齐 Ext change） */
+  onChange?: (values: string[]) => void;
+}
+/** 命令式句柄：对齐 Ext.ux.form.MultiSelect 的 getValue / setValue 与选择读取 */
+export interface MultiSelectHandle {
+  /** delimiter 分隔的字符串（对齐 Ext getValue） */
+  getValue: () => string;
+  /** 选中 value 数组（对齐 Ext getRawValue） */
+  getRawValue: () => string[];
+  /** 设置选中：字符串（delimiter 分隔）或数组 */
+  setValue: (v: string | string[]) => void;
+  /** 选中项数据（value + text） */
+  getSelectedItems: () => MultiSelectDataItem[];
+  /** 清空选择（对齐 Ext reset） */
+  clear: () => void;
+  disable: () => void;
+  enable: () => void;
+  focus: () => void;
+}
+const normalizeMultiData = (data?: MultiSelectData): MultiSelectDataItem[] => {
+  if (!data) return [];
+  return data.map((d) => {
+    if (typeof d === 'string' || typeof d === 'number') return { value: String(d), text: String(d) };
+    if (Array.isArray(d)) return { value: String(d[0]), text: String(d[1] ?? d[0]) };
+    return { value: String(d.value), text: String(d.text ?? d.value) };
+  });
+};
+export const MultiSelect = forwardRef<MultiSelectHandle, MultiSelectProps>(function MultiSelect(
+  {
+    id,
+    name,
+    width = 200,
+    height = 100,
+    legend,
+    data,
+    value,
+    delimiter = ',',
+  disabled,
+  tbar,
+  cls,
+  style,
+  onChange,
+},
+  ref,
+) {
+  const items = useMemo(() => normalizeMultiData(data), [data]);
+  // value 对齐 Ext 的「初始默认选中项」语义：仅作为首次渲染的初始值，
+  // 之后的选择由内部 selected 维护（对齐 Ext.ux.form.MultiSelect 内部态），
+  // onChange 单向通知父级，父级无需回灌 value。
+  const [selected, setSelected] = useState<number[]>(() => {
+    if (value === undefined) return [];
+    const arr = (Array.isArray(value) ? value : String(value).split(delimiter)).map(String);
+    return items.reduce<number[]>((acc, it, i) => {
+      if (arr.includes(String(it.value))) acc.push(i);
+      return acc;
+    }, []);
+  });
+  const lastIndex = useRef<number | null>(null);
+  const [disabledState, setDisabledState] = useState(!!disabled);
+  const bodyRef = useRef<HTMLDivElement>(null);
+
+  const emit = useCallback(
+    (idx: number[]) => {
+      const vals = idx.map((i) => items[i].value);
+      onChange?.(vals);
+    },
+    [items, onChange],
+  );
+
+  const selectByIndex = useCallback(
+    (idx: number[]) => {
+      setSelected(idx);
+      emit(idx);
+    },
+    [emit],
+  );
+
+  // value 同步：仅在 value 内容「相对上一次已应用值」真正发生变化时才回写 selected，
+  // 避免父级每次渲染传入新的字面量数组（如 value={['b','d']}）触发 effect 反复覆盖内部选择。
+  const valueSigRef = useRef<string>('');
+  const prevItemsRef = useRef(items);
+  useEffect(() => {
+    if (value === undefined) return;
+    const arr = (Array.isArray(value) ? value : String(value).split(delimiter)).map(String);
+    const sig = [...arr].sort().join('|');
+    const itemsChanged = prevItemsRef.current !== items;
+    if (valueSigRef.current === sig && !itemsChanged) return; // 同一 value 已应用过，保留内部编辑
+    valueSigRef.current = sig;
+    prevItemsRef.current = items;
+    const idx = items.reduce<number[]>((acc, it, i) => {
+      if (arr.includes(String(it.value))) acc.push(i);
+      return acc;
+    }, []);
+    setSelected(idx);
+  }, [value, items, delimiter]);
+
+  const handleClick = (i: number, e: React.MouseEvent) => {
+    if (disabledState) return;
+    if (e.ctrlKey || e.metaKey) {
+      const cur = selected.includes(i) ? selected.filter((x) => x !== i) : [...selected, i];
+      lastIndex.current = i;
+      selectByIndex(cur);
+    } else if (e.shiftKey && lastIndex.current != null) {
+      const [a, b] = [lastIndex.current, i].sort((x, y) => x - y);
+      const range: number[] = [];
+      for (let k = a; k <= b; k++) range.push(k);
+      selectByIndex(Array.from(new Set([...selected, ...range])));
+    } else {
+      lastIndex.current = i;
+      selectByIndex([i]);
+    }
+  };
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      getValue: () => selected.map((i) => items[i].value).join(delimiter),
+      getRawValue: () => selected.map((i) => items[i].value),
+      setValue: (v) => {
+        const arr = (Array.isArray(v) ? v : String(v).split(delimiter)).map(String);
+        const idx = items.reduce<number[]>((acc, it, i) => {
+          if (arr.includes(String(it.value))) acc.push(i);
+          return acc;
+        }, []);
+        selectByIndex(idx);
+      },
+      getSelectedItems: () => selected.map((i) => items[i]),
+      clear: () => selectByIndex([]),
+      disable: () => setDisabledState(true),
+      enable: () => setDisabledState(false),
+      focus: () => bodyRef.current?.focus(),
+    }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [selected, items, delimiter],
+  );
+
+  const hiddenValue = selected.map((i) => items[i].value).join(delimiter);
+
+  const fsClass = ['x-fieldset', 'x-multiselect', disabledState ? 'x-item-disabled' : '', cls]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <span style={{ display: 'inline-block', ...style }}>
+      <fieldset className={fsClass} style={width != null ? { width } : undefined}>
+        {legend != null && (
+          <legend className="x-fieldset-header x-unselectable">
+            <span className="x-fieldset-header-text">{legend}</span>
+          </legend>
+        )}
+        <div className="x-fieldset-bwrap">
+          {tbar && tbar.length > 0 && (
+            <div className="x-multiselect-tbar">
+              {tbar.map((b, bi) => (
+                <Button
+                  key={bi}
+                  text={b.text}
+                  scale="small"
+                  disabled={b.disabled || disabledState}
+                  onClick={b.onClick}
+                />
+              ))}
+            </div>
+          )}
+          <div
+            className="x-fieldset-body ux-mselect"
+            style={{ height, overflow: 'auto' }}
+            ref={bodyRef}
+            tabIndex={disabledState ? -1 : 0}
+          >
+            {items.map((it, i) => {
+              const isSel = selected.includes(i);
+              return (
+                <div
+                  key={i}
+                  className={['ux-mselect-item', isSel ? 'ux-mselect-selected' : ''].filter(Boolean).join(' ')}
+                  onClick={(e) => handleClick(i, e)}
+                  onDoubleClick={() => emit(selected)}
+                >
+                  {it.text}
+                </div>
+              );
+            })}
+          </div>
+        </div>
+      </fieldset>
+      <input type="hidden" name={name || id} value={hiddenValue} disabled={disabledState} />
+    </span>
+  );
+});
+MultiSelect.displayName = 'MultiSelect';
+
+/* ------------------------------------------------------------------ */
+/* Label —— 复刻 Ext.form.Label（独立文本标签，可关联字段 forId）     */
+/* onRender：forId 存在时渲染 <label for>，否则 <span>；              */
+/* text 经 htmlEncode，html 原样注入（对齐 Ext 二选一）。            */
+/* ------------------------------------------------------------------ */
+export interface LabelProps {
+  id?: string;
+  /** 关联的字段 id（对齐 Ext forId），设置后渲染为 <label for> 并可点击聚焦该字段 */
+  forId?: string;
+  /** 纯文本（对齐 Ext text），自动 HTML 转义 */
+  text?: ReactNode;
+  /** 原始 HTML（对齐 Ext html），与 text 二选一，优先级高于 text */
+  html?: string;
+  cls?: string;
+  style?: CSSProperties;
+  onClick?: (e: React.MouseEvent) => void;
+}
+export function Label({ id, forId, text, html, cls, style, onClick }: LabelProps) {
+  const className = ['x-form-label-item', cls].filter(Boolean).join(' ');
+  const common = { id, className, style, onClick };
+  if (forId) {
+    return (
+      <label htmlFor={forId} {...common}>
+        {html != null ? <span dangerouslySetInnerHTML={{ __html: html }} /> : text}
+      </label>
+    );
+  }
+  return (
+    <span {...common}>
+      {html != null ? <span dangerouslySetInnerHTML={{ __html: html }} /> : text}
+    </span>
+  );
+}
+Label.displayName = 'Label';
+
+/* ------------------------------------------------------------------ */
+/* CompositeField —— 复刻 Ext.form.CompositeField                     */
+/* 将多个子字段渲染在同一行，共享单一 fieldLabel；getValue 返回子字段   */
+/* 值数组、setValue 接收数组按序写入（对齐 Ext combineErrors/items）。  */
+/* 子字段需为支持 getValue/setValue 的命令式句柄组件（本工程表单家族  */
+/* 字段均满足）；无句柄的子节点（纯文本/span）会被安全跳过。          */
+/* ------------------------------------------------------------------ */
+export interface CompositeFieldHandle {
+  /** 返回各子字段当前值（顺序与 children 一致；无句柄者返回 undefined） */
+  getValue: () => unknown[];
+  /** 按数组顺序将值写入各子字段（长度不必与子字段数一致，越界忽略） */
+  setValue: (values: unknown[]) => void;
+  /** 聚焦首个可聚焦子字段 */
+  focus: () => void;
+}
+export interface CompositeFieldProps {
+  id?: string;
+  /** 共享标签（对齐 Ext fieldLabel） */
+  fieldLabel?: ReactNode;
+  labelAlign?: 'left' | 'top' | 'right';
+  labelWidth?: number;
+  labelPad?: number;
+  labelSeparator?: string;
+  hideLabel?: boolean;
+  /** 子字段之间的分隔符（对齐 Ext separator，默认单个空格） */
+  separator?: string;
+  /** 子字段节点（任意表单字段组件或纯展示节点） */
+  children?: ReactNode;
+  cls?: string;
+  style?: CSSProperties;
+}
+export const CompositeField = forwardRef<CompositeFieldHandle, CompositeFieldProps>(
+  function CompositeField(
+    {
+      id,
+      fieldLabel,
+      labelAlign = 'left',
+      labelWidth = 100,
+      labelPad = 5,
+      labelSeparator = ':',
+      hideLabel,
+      separator = ' ',
+      children,
+      cls,
+      style,
+    },
+    ref,
+  ) {
+    const childRefs = useRef<unknown[]>([]);
+
+    const collect = (el: unknown, idx: number) => {
+      childRefs.current[idx] = el;
+    };
+
+    const nodes = Children.toArray(children).filter((c) => c != null);
+
+    const rendered = nodes.map((child, i) => {
+      const sep =
+        i > 0 ? (
+          <span key={`sep-${i}`} className="x-composite-separator">
+            {separator}
+          </span>
+        ) : null;
+      let field: ReactNode = child;
+      if (isValidElement(child)) {
+        // 给子字段注入 ref（与既有 ref 合并），供句柄读取/写入
+        const origRef = (child as ReactElement & { ref?: React.Ref<unknown> }).ref;
+        field = cloneElement(child as ReactElement, {
+          ref: (el: unknown) => {
+            collect(el, i);
+            if (typeof origRef === 'function') (origRef as (v: unknown) => void)(el);
+            else if (origRef && typeof origRef === 'object')
+              (origRef as React.MutableRefObject<unknown>).current = el;
+          },
+        } as Partial<unknown>);
+      }
+      return (
+        <Fragment key={`c-${i}`}>
+          {sep}
+          {field}
+        </Fragment>
+      );
+    });
+
+    useImperativeHandle(ref, () => ({
+      getValue: () =>
+        childRefs.current.map((r) =>
+          r && typeof (r as { getValue?: () => unknown }).getValue === 'function'
+            ? (r as { getValue: () => unknown }).getValue()
+            : undefined,
+        ),
+      setValue: (values: unknown[]) => {
+        values.forEach((v, i) => {
+          const r = childRefs.current[i];
+          if (r && typeof (r as { setValue?: (v: unknown) => void }).setValue === 'function')
+            (r as { setValue: (v: unknown) => void }).setValue(v);
+        });
+      },
+      focus: () => {
+        const first = childRefs.current.find(
+          (r) => r && typeof (r as { focus?: () => void }).focus === 'function',
+        );
+        if (first) (first as { focus: () => void }).focus();
+      },
+    }));
+
+    const isTop = labelAlign === 'top';
+    const labelStyle: CSSProperties = isTop ? { width: 'auto' } : { width: `${labelWidth}px` };
+    const itemClass = ['x-form-item', `x-form-label-${labelAlign}`]
+      .filter(Boolean)
+      .join(' ');
+    const compositeClass = ['x-form-composite', cls].filter(Boolean).join(' ');
+
+    return (
+      <div className={itemClass} tabIndex={-1} id={id}>
+        {!hideLabel && fieldLabel != null && (
+          <label style={labelStyle} className="x-form-item-label">
+            {fieldLabel}
+            {labelSeparator}
+          </label>
+        )}
+        <div
+          className="x-form-element"
+          style={isTop ? { paddingLeft: 0 } : { paddingLeft: `${labelWidth + labelPad}px` }}
+        >
+          <div className={compositeClass} style={style}>
+            {rendered}
+          </div>
+        </div>
+        <div className="x-form-clear-left"></div>
+      </div>
+    );
+  },
+);
+CompositeField.displayName = 'CompositeField';
+
+/* ------------------------------------------------------------------ */
+/* ComboBox —— 复刻 TriggerField + Combo 下拉                         */
+/* ------------------------------------------------------------------ */
+export interface ComboItem {
+  value: string;
+  text: string;
+}
+export interface ComboBoxProps {
+  id?: string;
+  name?: string;
+  value?: string;
+  width?: number;
+  editable?: boolean;
+  disabled?: boolean;
+  /** 输入时前缀唯一匹配自动补全（等价 Ext typeAhead）：键入串作为前缀匹配首项并补全剩余文本、高亮补全部分 */
+  typeAhead?: boolean;
+  data: ComboItem[];
+  onChange?: (value: string) => void;
+  /** 透传 ref：暴露 setData / addItem / removeItem / getData / setValue（对齐 Ext combo.getStore().loadData / add / remove / setValue）。 */
+  ref?: React.Ref<ComboBoxHandle>;
+}
+
+/** ComboBox 命令句柄（对齐 Ext ComboBox 数据源运行时编辑）。 */
+export interface ComboBoxHandle {
+  /** 整体替换数据源（等价 Ext store.loadData），不破坏 value 受控场景 */
+  setData: (items: ComboItem[]) => void;
+  /** 追加一项到末尾 */
+  addItem: (item: ComboItem) => void;
+  /** 按 value 移除一项 */
+  removeItem: (value: string) => void;
+  /** 读取当前数据源（含动态追加/移除后的结果） */
+  getData: () => ComboItem[];
+  /** 程序化选中某项（等价 Ext combo.setValue） */
+  setValue: (value: string) => void;
+  /** 读取当前选中值（等价 Ext combo.getValue） */
+  getValue: () => string;
+}
+export const ComboBox = forwardRef<ComboBoxHandle, ComboBoxProps>((
+  {
+    id,
+    name,
+    value,
+    width,
+    editable = true,
+    disabled,
+    typeAhead = false,
+    data,
+    onChange,
+  },
+  ref,
+) => {
+  const [internal, setInternal] = useState(value ?? '');
+  const current = value !== undefined ? value : internal;
+  const [focused, setFocused] = useState(false);
+  const [open, setOpen] = useState(false);
+  // 复刻 ExtJS Combo.selectByValue / onViewOver：展开时高亮选中值对应项，
+  // 鼠标悬停或用方向键导航时高亮跟随移动，x-combo-selected 落到 highlight 项（而非 CSS :hover）。
+  const [highlight, setHighlight] = useState<string | null>(null);
+  // 用户输入的过滤串（null 表示未处于“正在输入”状态，应回显选中项的 display 文本）。
+  // 对齐 Ext Combo 的 query：键入即按 text/value 过滤下拉项并展开。
+  const [typed, setTyped] = useState<string | null>(null);
+  // typeAhead 自动补全后的完整文本（null 表示无补全）；输入框显示 completion ?? typed ?? resolved。
+  const [completion, setCompletion] = useState<string | null>(null);
+  // 浮层用 Portal 渲染到 body（与 Ext 一致），脱离 .x-panel-body 的 overflow:hidden 截断。
+  const wrapRef = useRef<HTMLSpanElement>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+  // 待应用的补全文本选区（尾部高亮）：在 layout effect 中落到真实 input 上。
+  const pendingSel = useRef<[number, number] | null>(null);
+  const [coords, setCoords] = useState<{ top: number; left: number } | null>(null);
+  // 双轨：data prop 为静态数据源来源；dynamicData 为独立动态态（默认 null 表示沿用 prop）。
+  // 对齐 Ext combo.getStore().loadData / add / remove。未调用动态方法时 managedData 恒等于 data，零回归。
+  const [dynamicData, setDynamicData] = useState<ComboItem[] | null>(null);
+  const managedData = useMemo<ComboItem[]>(
+    () => dynamicData ?? data,
+    [dynamicData, data],
+  );
+
+  // 对齐 Ext Combo query：按 typed 过滤下拉项（text 或 value 包含，忽略大小写）。
+  const filteredData = useMemo(() => {
+    if (typed == null) return managedData;
+    const q = typed.toLowerCase();
+    return managedData.filter(
+      (d) => d.text.toLowerCase().includes(q) || d.value.toLowerCase().includes(q),
+    );
+  }, [typed, managedData]);
+
+  // 展开时初始化高亮项：对齐 Ext 的 selectByValue(value)，无匹配则选中首项。
+  // 处于输入过滤态时，高亮过滤结果的首项。
+  useEffect(() => {
+    if (!open) return;
+    if (typed !== null) {
+      setHighlight(filteredData[0]?.value ?? null);
+    } else {
+      setHighlight(
+        managedData.some((d) => d.value === current)
+          ? current
+          : managedData[0]?.value ?? null,
+      );
+    }
+  }, [open, typed, current, managedData, filteredData]);
+
+  // 同步计算浮层坐标（在点击瞬间执行，避免首帧 coords 为 null 导致下拉不渲染）。
+  // 对齐 Ext.Layer：用整数视口坐标 + fixed 定位；若字段靠近视口底部则向上翻转展开，避免溢出被裁剪。
+  const openDropdown = useCallback(() => {
+    const el = wrapRef.current;
+    if (el) {
+      const r = el.getBoundingClientRect();
+      const estH = (Math.min(filteredData.length || 1, 10) * 22) + 6;
+      const below = window.innerHeight - r.bottom >= estH;
+      setCoords({
+        top: Math.round(below ? r.bottom : r.top - estH),
+        left: Math.round(r.left),
+      });
+    }
+    setOpen(true);
+  }, [filteredData]);
+
+  // 点击切换：已开则关（并清除过滤串），未开则同步打开并定位。
+  const toggle = useCallback(() => {
+    if (open) {
+      setOpen(false);
+      setTyped(null);
+      return;
+    }
+    openDropdown();
+  }, [open, openDropdown]);
+
+  // 对齐 Ext：点击组件外部、滚动或缩放窗口时关闭下拉（滚动关闭避免浮层悬空错位）。
+  useEffect(() => {
+    if (!open) return;
+    const onDocDown = (e: MouseEvent) => {
+      const target = e.target as HTMLElement;
+      if (!target.closest('.x-form-field-trigger-wrap') && !target.closest('.x-combo-list')) {
+        setOpen(false);
+      }
+    };
+    const close = () => {
+      setOpen(false);
+      // 保留 completion（typeAhead 补全文本）；仅清除输入过滤串，避免误把补全文本回退为选中项 display。
+      setTyped(null);
+    };
+    document.addEventListener('mousedown', onDocDown);
+    window.addEventListener('resize', close);
+    // capture 捕获文档站 .docs-content 等任意滚动容器的平滑滚动
+    window.addEventListener('scroll', close, true);
+    return () => {
+      document.removeEventListener('mousedown', onDocDown);
+      window.removeEventListener('resize', close);
+      window.removeEventListener('scroll', close, true);
+    };
+  }, [open]);
+
+  // 输入框回显：typeAhead 补全态显示补全文本，否则处于输入过滤态显示键入串，否则回显选中项的 display 文本（对齐 Ext）。
+  const resolved = managedData.find((d) => d.value === current)?.text ?? current;
+  const display = completion ?? (typed !== null ? typed : resolved);
+
+  // typeAhead：补全文本渲染后，把尾部补全部分高亮选中（对齐 Ext doTypeAhead 的 setSelectionRange）。
+  useLayoutEffect(() => {
+    if (pendingSel.current && inputRef.current) {
+      const [s, e] = pendingSel.current;
+      pendingSel.current = null;
+      try {
+        inputRef.current.focus();
+        inputRef.current.setSelectionRange(s, e);
+      } catch {
+        /* 某些环境 input 尚未 mount，忽略 */
+      }
+    }
+  });
+
+  const select = useCallback(
+    (v: string) => {
+      if (value === undefined) setInternal(v);
+      setTyped(null);
+      setCompletion(null);
+      setOpen(false);
+      onChange?.(v);
+    },
+    [value, onChange],
+  );
+
+  // 命令句柄：运行时数据源编辑（对齐 Ext combo.getStore().loadData / add / remove / setValue）。
+  // 源数据走 managedData（data prop + dynamicData 双轨），不破坏 value 受控场景。
+  useImperativeHandle(ref, () => ({
+    setData: (items: ComboItem[]) => {
+      setDynamicData(items);
+      // 清空正在输入的过滤串，避免旧 query 滞留。
+      setTyped(null);
+    },
+    addItem: (item: ComboItem) => {
+      setDynamicData((prev) => [...(prev ?? data), item]);
+    },
+    removeItem: (val: string) => {
+      setDynamicData((prev) => (prev ?? data).filter((d) => d.value !== val));
+    },
+    getData: () => managedData,
+    setValue: (val: string) => select(val),
+    getValue: () => current,
+  }), [managedData, data, select, current]);
+
+  // 键盘导航：对齐 Ext Combo.onKeyDown 的 selectNext/selectPrev（到边界回环）/ Enter 选中 / Esc 收起。
+  // 导航范围基于过滤后的 filteredData。
+  const onKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+    if (!open) {
+      if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+        e.preventDefault();
+        openDropdown();
+      }
+      return;
+    }
+    const idx = filteredData.findIndex((d) => d.value === highlight);
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      const next = filteredData.length ? (idx + 1) % filteredData.length : 0;
+      setHighlight(filteredData[next]?.value ?? null);
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      const prev = filteredData.length ? (idx - 1 + filteredData.length) % filteredData.length : 0;
+      setHighlight(filteredData[prev]?.value ?? null);
+    } else if (e.key === 'Enter') {
+      e.preventDefault();
+      if (highlight != null) select(highlight);
+    } else if (e.key === 'Escape') {
+      e.preventDefault();
+      setOpen(false);
+    }
+  };
+
+  const wrapClass = ['x-form-field-wrap', 'x-form-field-trigger-wrap', focused ? 'x-trigger-wrap-focus' : '']
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <span style={{ position: 'relative', display: 'inline-block' }}>
+      <span ref={wrapRef} className={wrapClass} style={{ display: 'flex', alignItems: 'stretch', ...(width ? { width } : {}) }}>
+        <input
+          ref={inputRef}
+          id={id}
+          name={name}
+          type="text"
+          className="x-form-field x-form-text"
+          value={display}
+          readOnly={!editable}
+          disabled={disabled}
+          style={{ flex: '1 1 auto', minWidth: 0, height: 22, boxSizing: 'border-box' }}
+          onFocus={() => setFocused(true)}
+          onBlur={() => setFocused(false)}
+          onClick={toggle}
+          onKeyDown={onKeyDown}
+          onChange={(e) => {
+            if (!editable) return;
+            const v = e.target.value;
+            // 对齐 Ext Combo query：键入即过滤下拉项并展开
+            setTyped(v);
+            openDropdown();
+            if (value === undefined) setInternal(v);
+            // typeAhead：前缀唯一匹配则补全剩余文本并高亮补全部分（对齐 Ext doTypeAhead）
+            if (typeAhead) {
+              if (v) {
+                const m = managedData.find(
+                  (d) =>
+                    d.text.toLowerCase().startsWith(v.toLowerCase()) &&
+                    d.text.length > v.length,
+                );
+                if (m) {
+                  setCompletion(m.text);
+                  pendingSel.current = [v.length, m.text.length];
+                } else {
+                  setCompletion(null);
+                }
+              } else {
+                setCompletion(null);
+              }
+            }
+          }}
+        />
+        <img
+          className="x-form-trigger x-form-arrow-trigger"
+          src={BLANK_IMG}
+          alt=""
+          style={{ flex: '0 0 auto' }}
+          onClick={() => !disabled && toggle()}
+        />
+      </span>
+      {open && coords &&
+        createPortal(
+          <div
+            className="x-combo-list x-layer"
+            style={{ position: 'fixed', visibility: 'visible', zIndex: 15000, top: coords.top, left: coords.left, width: width ? width : undefined, boxSizing: 'border-box' }}
+          >
+            <div className="x-combo-list-inner">
+              {filteredData.map((d) => (
+                <div
+                  key={d.value}
+                  className={[
+                    'x-combo-list-item',
+                    d.value === highlight ? 'x-combo-selected' : '',
+                  ]
+                    .filter(Boolean)
+                    .join(' ')}
+                  onMouseEnter={() => setHighlight(d.value)}
+                  onClick={() => select(d.value)}
+                >
+                  {d.text}
+                </div>
+              ))}
+            </div>
+          </div>,
+          getPortalRoot(),
+        )}
+    </span>
+  );
+});
+
+/* ------------------------------------------------------------------ */
+/* SelectBox —— 复刻 Ext.ux.form.SelectBox（继承 ComboBox）            */
+/* 差异行为（对齐 examples/ux/SelectBox.js）：                          */
+/*  1) 强制 editable:false / forceSelection / triggerAction:'all' /     */
+/*     mode:'local'；输入框只读，点击触发器展开全量列表。               */
+/*  2) 键盘逐字搜索（type-through）：聚焦时键入字母按 displayField 前缀  */
+/*     匹配并跳转到对应项；重复同字母从上一命中后继续（lastSearchTerm）。 */
+/*  3) 列表「按下拖动、松开选择」：对齐原生 SELECT，onMouseUp 才提交选择  */
+/*     （而非 ComboBox 的 onClick 立即选择），可拖动滑过列表松手落定。  */
+/*  4) HOME/END/PAGEUP/PAGEDOWN 导航。                                  */
+/* 注：原 Ext 每次按键会立即选中且收起下拉（历史 quirk）；本项目保持下拉 */
+/* 展开以便连续输入定位，属保真等效优化。DOM/class 复用 ComboBox 套件。  */
+/* ------------------------------------------------------------------ */
+export interface SelectBoxProps {
+  id?: string;
+  name?: string;
+  value?: string;
+  width?: number;
+  disabled?: boolean;
+  emptyText?: string;
+  placeholder?: string;
+  /** 数据源（对齐 Ext local store） */
+  data: ComboItem[];
+  /** 搜索复位延时（对齐 Ext searchResetDelay，默认 1000ms） */
+  searchResetDelay?: number;
+  onChange?: (value: string) => void;
+}
+/** 命令式句柄：对齐 ComboBox（getValue / setValue / 数据源运行时编辑）。 */
+export type SelectBoxHandle = ComboBoxHandle;
+export const SelectBox = forwardRef<SelectBoxHandle, SelectBoxProps>((
+  {
+    id,
+    name,
+    value,
+    width,
+    disabled,
+    emptyText,
+    placeholder,
+    data,
+    searchResetDelay = 1000,
+    onChange,
+  },
+  ref,
+) => {
+  const isControlled = value !== undefined;
+  const [internal, setInternal] = useState(value ?? (data[0]?.value ?? ''));
+  const current = isControlled ? value! : internal;
+  const [focused, setFocused] = useState(false);
+  const [open, setOpen] = useState(false);
+  const [highlight, setHighlight] = useState<string | null>(null);
+  const [coords, setCoords] = useState<{ top: number; left: number } | null>(null);
+  const [dynamicData, setDynamicData] = useState<ComboItem[] | null>(null);
+  const managedData = useMemo<ComboItem[]>(() => dynamicData ?? data, [dynamicData, data]);
+  const wrapRef = useRef<HTMLSpanElement>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+  // 镜像最新 value，供命令式句柄同步读取（避免 React setState 异步导致 getValue 读旧值）
+  const valueRef = useRef<string>(current);
+  valueRef.current = current;
+  // 键盘搜索态（对齐 Ext lastSearchTerm / lastSelectedIndex，1-based）
+  const lastTerm = useRef<string | false>(false);
+  const lastIndex = useRef<number>(0);
+  const resetTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const resetSearch = useCallback(() => {
+    lastTerm.current = false;
+    lastIndex.current = 0;
+  }, []);
+
+  const openDropdown = useCallback(() => {
+    const el = wrapRef.current;
+    if (el) {
+      const r = el.getBoundingClientRect();
+      const estH = (Math.min(managedData.length || 1, 10) * 22) + 6;
+      const below = window.innerHeight - r.bottom >= estH;
+      setCoords({ top: Math.round(below ? r.bottom : r.top - estH), left: Math.round(r.left) });
+    }
+    setOpen(true);
+    if (highlight == null) setHighlight(current || managedData[0]?.value || null);
+  }, [managedData, highlight, current]);
+
+  const closeDropdown = useCallback(() => {
+    setOpen(false);
+    resetSearch();
+  }, [resetSearch]);
+
+  // 提交选中（对齐 Ext onSelect：setValue + 收起 + 触发 select）
+  const commit = useCallback(
+    (v: string) => {
+      if (!isControlled) setInternal(v);
+      setHighlight(v);
+      setOpen(false);
+      resetSearch();
+      onChange?.(v);
+    },
+    [isControlled, onChange, resetSearch],
+  );
+
+  // 仅高亮预览（键盘逐字搜索时保持下拉展开，便于连续定位）
+  const preview = useCallback(
+    (v: string) => {
+      if (!isControlled) setInternal(v);
+      setHighlight(v);
+      onChange?.(v);
+    },
+    [isControlled, onChange],
+  );
+
+  // 键盘逐字搜索（前缀匹配 displayField，重复同字母从上一命中后继续）
+  const typeSearch = useCallback(
+    (key: string) => {
+      const k = key.toLowerCase();
+      const start = lastTerm.current === key ? lastIndex.current : 0;
+      const n = managedData.length;
+      let found = -1;
+      for (let i = 0; i < n; i++) {
+        const idx = (start + i) % n;
+        if (managedData[idx].text.toLowerCase().startsWith(k)) {
+          found = idx;
+          break;
+        }
+      }
+      if (found !== -1) {
+        const v = managedData[found].value;
+        lastTerm.current = key;
+        lastIndex.current = found + 1;
+        preview(v);
+        if (resetTimer.current) clearTimeout(resetTimer.current);
+        resetTimer.current = setTimeout(() => resetSearch(), searchResetDelay);
+      }
+    },
+    [managedData, preview, resetSearch, searchResetDelay],
+  );
+
+  useEffect(() => {
+    if (resetTimer.current) return () => clearTimeout(resetTimer.current ?? undefined);
+  }, [open]);
+
+  useEffect(() => {
+    if (!open) return;
+    const onDocDown = (e: MouseEvent) => {
+      const t = e.target as HTMLElement;
+      if (!t.closest('.x-form-field-trigger-wrap') && !t.closest('.x-combo-list')) setOpen(false);
+    };
+    const close = () => setOpen(false);
+    document.addEventListener('mousedown', onDocDown);
+    window.addEventListener('resize', close);
+    window.addEventListener('scroll', close, true);
+    return () => {
+      document.removeEventListener('mousedown', onDocDown);
+      window.removeEventListener('resize', close);
+      window.addEventListener('scroll', close, true);
+    };
+  }, [open]);
+
+  const moveHighlight = useCallback(
+    (delta: number, pageSize = false) => {
+      const n = managedData.length;
+      if (!n) return;
+      const cur = managedData.findIndex((d) => d.value === highlight);
+      const step = pageSize ? Math.max(1, Math.min(10, n)) : 1;
+      const next = ((cur === -1 ? 0 : cur) + delta * step + n) % n;
+      setHighlight(managedData[next].value);
+    },
+    [managedData, highlight],
+  );
+
+  const onKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+    const printable = e.key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey;
+    if (!open) {
+      if (['ArrowDown', 'ArrowUp', 'Home', 'End', 'PageDown', 'PageUp'].includes(e.key) || printable) {
+        e.preventDefault();
+        openDropdown();
+        if (e.key === 'Home') { const f = managedData[0]; if (f) { preview(f.value); setHighlight(f.value); } }
+        else if (e.key === 'End') { const l = managedData[managedData.length - 1]; if (l) { preview(l.value); setHighlight(l.value); } }
+        else if (printable) typeSearch(e.key);
+      }
+      return;
+    }
+    if (e.key === 'ArrowDown') { e.preventDefault(); moveHighlight(1); }
+    else if (e.key === 'ArrowUp') { e.preventDefault(); moveHighlight(-1); }
+    else if (e.key === 'PageDown') {
+      e.preventDefault();
+      const cur = managedData.findIndex((d) => d.value === (highlight ?? current));
+      const idx = Math.min(managedData.length - 1, cur + Math.max(1, Math.min(10, managedData.length)));
+      preview(managedData[idx].value); setHighlight(managedData[idx].value);
+    }
+    else if (e.key === 'PageUp') {
+      e.preventDefault();
+      const cur = managedData.findIndex((d) => d.value === (highlight ?? current));
+      const idx = Math.max(0, cur - Math.max(1, Math.min(10, managedData.length)));
+      preview(managedData[idx].value); setHighlight(managedData[idx].value);
+    }
+    else if (e.key === 'Home') { e.preventDefault(); if (managedData[0]) { preview(managedData[0].value); setHighlight(managedData[0].value); } }
+    else if (e.key === 'End') { e.preventDefault(); const last = managedData[managedData.length - 1]; if (last) { preview(last.value); setHighlight(last.value); } }
+    else if (e.key === 'Enter') { e.preventDefault(); if (highlight != null) commit(highlight); }
+    else if (e.key === 'Escape') { e.preventDefault(); closeDropdown(); }
+    else if (printable) { e.preventDefault(); typeSearch(e.key); }
+  };
+
+  const resolved = managedData.find((d) => d.value === current)?.text ?? current;
+  const wrapClass = ['x-form-field-wrap', 'x-form-field-trigger-wrap', focused ? 'x-trigger-wrap-focus' : '']
+    .filter(Boolean)
+    .join(' ');
+
+  // 命令式句柄（对齐 Ext.ux.form.SelectBox 继承 ComboBox 的 getValue / setValue / setData / addItem / removeItem / getData）
+  useImperativeHandle(ref, () => ({
+    setData: (items: ComboItem[]) => setDynamicData(items),
+    addItem: (item: ComboItem) => setDynamicData((prev) => [...(prev ?? data), item]),
+    removeItem: (val: string) => setDynamicData((prev) => (prev ?? data).filter((d) => d.value !== val)),
+    getData: () => managedData,
+    setValue: (val: string) => commit(val),
+    getValue: () => valueRef.current,
+  }), [managedData, data, commit]);
+
+  return (
+    <span style={{ position: 'relative', display: 'inline-block' }}>
+      <span ref={wrapRef} className={wrapClass} style={{ display: 'flex', alignItems: 'stretch', ...(width ? { width } : {}) }}>
+        <input
+          ref={inputRef}
+          id={id}
+          name={name}
+          type="text"
+          className="x-form-field x-form-text"
+          value={resolved}
+          readOnly
+          disabled={disabled}
+          placeholder={placeholder ?? emptyText}
+          style={{ flex: '1 1 auto', minWidth: 0, height: 22, boxSizing: 'border-box' }}
+          onFocus={() => setFocused(true)}
+          onBlur={() => setFocused(false)}
+          onClick={() => !disabled && openDropdown()}
+          onKeyDown={onKeyDown}
+        />
+        <img
+          className="x-form-trigger x-form-arrow-trigger"
+          src={BLANK_IMG}
+          alt=""
+          style={{ flex: '0 0 auto' }}
+          onMouseDown={(e) => {
+            if (disabled) return;
+            e.preventDefault();
+            if (open) closeDropdown();
+            else openDropdown();
+          }}
+        />
+      </span>
+      {open && coords &&
+        createPortal(
+          <div
+            className="x-combo-list x-layer"
+            style={{ position: 'fixed', visibility: 'visible', zIndex: 15000, top: coords.top, left: coords.left, width: width ? width : undefined, boxSizing: 'border-box' }}
+            onMouseUp={() => {
+              // 松开即落定（对齐 Ext innerList.on('mouseup', onViewClick)）
+              if (highlight != null) commit(highlight);
+            }}
+          >
+            <div className="x-combo-list-inner">
+              {managedData.map((d) => (
+                <div
+                  key={d.value}
+                  className={[
+                    'x-combo-list-item',
+                    d.value === highlight ? 'x-combo-selected' : '',
+                  ]
+                    .filter(Boolean)
+                    .join(' ')}
+                  onMouseDown={() => setHighlight(d.value)}
+                  onMouseEnter={() => {
+                    setHighlight(d.value);
+                    lastIndex.current = managedData.findIndex((x) => x.value === d.value) + 1;
+                  }}
+                >
+                  {d.text}
+                </div>
+              ))}
+            </div>
+          </div>,
+          getPortalRoot(),
+        )}
+    </span>
+  );
+});
+SelectBox.displayName = 'SelectBox';
+
+/* ------------------------------------------------------------------ */
+/* TimeField —— 复刻 Ext.form.TimeField（继承 ComboBox，时间点下拉） */
+/* 默认 format 'g:i A'、increment 30 分钟、区间 12:00 AM ~ 11:30 PM。 */
+/* 行为契约：与 ComboBox 完全一致（展开/选中/外部点击关闭），        */
+/* 仅 data 由 min/max/increment 生成。trigger 复用 x-form-arrow-trigger。 */
+/* ------------------------------------------------------------------ */
+export interface TimeFieldProps {
+  id?: string;
+  name?: string;
+  value?: string;
+  width?: number;
+  disabled?: boolean;
+  /** 分钟增量，默认 30 */
+  increment?: number;
+  /** 起始时间（'g:i A'，默认 '12:00 AM'） */
+  minValue?: string;
+  /** 结束时间（默认 '11:30 PM'） */
+  maxValue?: string;
+  /** 显示格式，默认 'g:i A'（如 10:00 AM） */
+  format?: string;
+  onChange?: (value: string) => void;
+}
+function fmtTime(h: number, m: number, format: string) {
+  if (format === 'H:i') return `${h < 10 ? '0' + h : h}:${m < 10 ? '0' + m : m}`;
+  // 默认 g:i A
+  const period = h < 12 ? 'AM' : 'PM';
+  const hh = h % 12 === 0 ? 12 : h % 12;
+  return `${hh}:${m < 10 ? '0' + m : m} ${period}`;
+}
+export const TimeField = forwardRef<ComboBoxHandle, TimeFieldProps>(
+  (
+    {
+      id,
+      name,
+      value,
+      width,
+      disabled,
+      increment = 30,
+      minValue = '12:00 AM',
+      maxValue = '11:30 PM',
+      format = 'g:i A',
+      onChange,
+    },
+    ref,
+  ) => {
+    // 解析 12小时制 'g:i A' 边界为分钟数
+    const parseBound = (s: string) => {
+      const m = s.trim().match(/^(\d{1,2}):(\d{2})\s*(AM|PM)$/i);
+      if (!m) return 0;
+      let h = parseInt(m[1], 10) % 12;
+      if (m[3].toUpperCase() === 'PM') h += 12;
+      return h * 60 + parseInt(m[2], 10);
+    };
+    const start = parseBound(minValue);
+    const end = parseBound(maxValue);
+    const data: ComboItem[] = [];
+    for (let t = start; t <= end; t += increment) {
+      const h = Math.floor(t / 60);
+      const m = t % 60;
+      const label = fmtTime(h, m, format);
+      data.push({ value: label, text: label });
+    }
+    // 透传 handle 到内部 ComboBox：TimeField 继承 ComboBox 的动态数据源能力
+    // （setData/addItem/removeItem/getData/setValue），对齐 Ext TimeField 的 store 运行时编辑。
+    return (
+      <ComboBox
+        ref={ref}
+        id={id}
+        name={name}
+        value={value}
+        width={width}
+        disabled={disabled}
+        data={data}
+        onChange={onChange}
+      />
+    );
+  },
+);
+TimeField.displayName = 'TimeField';
+
+/* ------------------------------------------------------------------ */
+/* DateField —— 复刻 Ext.form.DateField（TriggerField + DateMenu）   */
+/* onRender：span.x-form-field-wrap.x-form-field-trigger-wrap        */
+/*          > input.x-form-text + img.x-form-trigger.x-form-date-trigger */
+/* 触发打开 DatePicker 浮层（x-menu.x-date-menu.x-menu-floating.x-layer）。*/
+/* 选中后 format('m/d/Y') 写入 input 并关闭；外部点击关闭。          */
+/* ------------------------------------------------------------------ */
+function pad2(n: number) {
+  return n < 10 ? `0${n}` : `${n}`;
+}
+function formatDate(d: Date, fmt: string) {
+  return fmt
+    .replace(/Y/g, String(d.getFullYear()))
+    .replace(/y/g, String(d.getFullYear()).slice(2))
+    .replace(/m/g, pad2(d.getMonth() + 1))
+    .replace(/d/g, pad2(d.getDate()));
+}
+function parseDate(s?: string) {
+  if (!s) return null;
+  const m = s.match(/^(\d{1,2})\/(\d{1,2})\/(\d{4})$/);
+  if (m) return new Date(+m[3], +m[1] - 1, +m[2]);
+  const m2 = s.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+  if (m2) return new Date(+m2[1], +m2[2] - 1, +m2[3]);
+  return null;
+}
+
+export interface DateFieldProps {
+  id?: string;
+  name?: string;
+  value?: string;
+  width?: number;
+  editable?: boolean;
+  disabled?: boolean;
+  /** 日期格式，默认 'm/d/Y'（如 05/04/2006） */
+  format?: string;
+  /** 最小可选日期（早于则 x-date-disabled） */
+  minDate?: Date | null;
+  /** 最大可选日期 */
+  maxDate?: Date | null;
+  /** 禁用的星期索引数组，如 [0,6] */
+  disabledDays?: number[];
+  onChange?: (value: string) => void;
+}
+/** 命令式句柄：对齐 Ext.DateField 的运行时 setMinValue/setMaxValue/setDisabledDays 与 getValue/setValue */
+export interface DateFieldHandle {
+  setMinDate: (d: Date | null) => void;
+  setMaxDate: (d: Date | null) => void;
+  setDisabledDays: (days: number[]) => void;
+  setValue: (v: string) => void;
+  getValue: () => string;
+}
+export const DateField = forwardRef<DateFieldHandle, DateFieldProps>(
+  (
+    {
+      id,
+      name,
+      value,
+      width,
+      editable = true,
+      disabled,
+      format = 'm/d/Y',
+      minDate,
+      maxDate,
+      disabledDays,
+      onChange,
+    },
+    ref,
+  ) => {
+  const [internal, setInternal] = useState(value ?? '');
+  const current = value !== undefined ? value : internal;
+  const [focused, setFocused] = useState(false);
+  const [open, setOpen] = useState(false);
+  const [triggerOver, setTriggerOver] = useState(false);
+  // 双轨：min/max/disabledDays 既接受静态 prop，也支持运行时通过句柄动态改写。
+  const [dynMin, setDynMin] = useState<Date | null | undefined>(minDate);
+  const [dynMax, setDynMax] = useState<Date | null | undefined>(maxDate);
+  const [dynDisabledDays, setDynDisabledDays] = useState<number[] | undefined>(disabledDays);
+  // 同步静态 prop 变化（演示中主要通过句柄改写，这里保证 prop 驱动也生效）
+  useEffect(() => setDynMin(minDate), [minDate]);
+  useEffect(() => setDynMax(maxDate), [maxDate]);
+  useEffect(() => setDynDisabledDays(disabledDays), [disabledDays]);
+
+  useImperativeHandle(ref, () => ({
+    setMinDate: (d) => setDynMin(d),
+    setMaxDate: (d) => setDynMax(d),
+    setDisabledDays: (days) => setDynDisabledDays(days),
+    setValue: (v) => {
+      if (value === undefined) setInternal(v);
+      onChange?.(v);
+    },
+    getValue: () => (value !== undefined ? value : internal),
+  }));
+  // 浮层用 Portal 渲染到 body（与 Ext 的 DateMenu.renderTo=document.body 一致），
+  // 脱离 .x-panel-body 的 overflow:hidden 截断；用视口坐标 fixed 定位到 trigger 正下方。
+  const wrapRef = useRef<HTMLSpanElement>(null);
+  const [coords, setCoords] = useState<{ top: number; left: number } | null>(null);
+
+  // 同步计算浮层坐标（在点击瞬间执行，避免首帧 coords 为 null 导致日历不渲染）。
+  // 对齐 Ext.Layer：整数视口坐标 + fixed 定位；字段靠近视口底部时向上翻转展开，避免溢出被裁剪。
+  const openDropdown = useCallback(() => {
+    const el = wrapRef.current;
+    if (el) {
+      const r = el.getBoundingClientRect();
+      // DatePicker（含头部/网格/底部）估算高度约 210px。
+      const estH = 210;
+      const below = window.innerHeight - r.bottom >= estH;
+      setCoords({
+        top: Math.round(below ? r.bottom : r.top - estH),
+        left: Math.round(r.left),
+      });
+    }
+    setOpen(true);
+  }, []);
+
+  // 点击切换：已开则关，未开则同步打开并定位。
+  const toggle = useCallback(() => {
+    if (open) {
+      setOpen(false);
+      return;
+    }
+    openDropdown();
+  }, [open, openDropdown]);
+
+  // 对齐 Ext：点击组件外部、滚动或缩放窗口时关闭浮层（滚动关闭避免浮层悬空错位）。
+  useEffect(() => {
+    if (!open) return;
+    const onDocDown = (e: MouseEvent) => {
+      const target = e.target as HTMLElement;
+      if (
+        !target.closest('.x-form-field-trigger-wrap') &&
+        !target.closest('.x-date-menu') &&
+        !target.closest('.x-date-picker')
+      ) {
+        setOpen(false);
+      }
+    };
+    const close = () => setOpen(false);
+    document.addEventListener('mousedown', onDocDown);
+    window.addEventListener('resize', close);
+    // capture 捕获文档站 .docs-content 等任意滚动容器的平滑滚动
+    window.addEventListener('scroll', close, true);
+    return () => {
+      document.removeEventListener('mousedown', onDocDown);
+      window.removeEventListener('resize', close);
+      window.removeEventListener('scroll', close, true);
+    };
+  }, [open]);
+
+  const selected = parseDate(current);
+
+  const wrapClass = ['x-form-field-wrap', 'x-form-field-trigger-wrap', focused ? 'x-trigger-wrap-focus' : '']
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <span style={{ position: 'relative', display: 'inline-block' }}>
+      <span ref={wrapRef} className={wrapClass} style={{ display: 'flex', alignItems: 'stretch', ...(width ? { width } : {}) }}>
+        <input
+          id={id}
+          name={name}
+          type="text"
+          className="x-form-field x-form-text"
+          value={current}
+          readOnly={!editable}
+          disabled={disabled}
+          style={{ flex: '1 1 auto', minWidth: 0, height: 22, boxSizing: 'border-box' }}
+          onFocus={() => setFocused(true)}
+          onBlur={() => setFocused(false)}
+          onClick={() => !disabled && toggle()}
+          onChange={(e) => {
+            if (value === undefined) setInternal(e.target.value);
+            onChange?.(e.target.value);
+          }}
+        />
+        <img
+          className={['x-form-trigger', 'x-form-date-trigger', triggerOver ? 'x-form-trigger-over' : '']
+            .filter(Boolean)
+            .join(' ')}
+          src={BLANK_IMG}
+          alt=""
+          style={{ flex: '0 0 auto' }}
+          onMouseEnter={() => setTriggerOver(true)}
+          onMouseLeave={() => setTriggerOver(false)}
+          onClick={() => !disabled && toggle()}
+        />
+      </span>
+      {open && coords &&
+        createPortal(
+          <div
+            className="x-menu x-date-menu x-menu-floating x-layer x-menu-plain"
+            style={{ position: 'fixed', visibility: 'visible', zIndex: 15000, top: coords.top, left: coords.left }}
+          >
+            <div className="x-menu-body">
+              <ul className="x-menu-list">
+                <li className="x-menu-list-item">
+                  <DatePicker
+                    className="x-menu-date-item"
+                    value={selected}
+                    minDate={dynMin ?? null}
+                    maxDate={dynMax ?? null}
+                    disabledDays={dynDisabledDays}
+                    onSelect={(d) => {
+                      const f = formatDate(d, format);
+                      if (value === undefined) setInternal(f);
+                      setOpen(false);
+                      onChange?.(f);
+                    }}
+                  />
+                </li>
+              </ul>
+            </div>
+          </div>,
+          getPortalRoot(),
+        )}
+    </span>
+  );
+});
+DateField.displayName = 'DateField';
+
+/* ------------------------------------------------------------------ */
+/* FormPanel —— 复刻 Ext.FormPanel（Panel + FormLayout）             */
+/* ------------------------------------------------------------------ */
+export interface FormPanelProps {
+  title?: string;
+  width?: number;
+  height?: number;
+  labelAlign?: 'left' | 'top' | 'right';
+  bodyPadding?: number;
+  frame?: boolean;
+  children?: ReactNode;
+}
+export function FormPanel({
+  title,
+  width,
+  height,
+  labelAlign = 'left',
+  bodyPadding = 10,
+  frame = true,
+  children,
+}: FormPanelProps) {
+  // 复用 Panel 容器，仅额外提供 x-form-label-* 容器类与 x-form-body。
+  // labelWidth/labelPad 由 FormField 默认值（left/100/5，与 Ext 一致）承接。
+  return (
+    <Panel title={title} width={width} height={height} frame={frame} bodyPadding={bodyPadding}>
+      <form className="x-form-body" style={{ padding: 0 }}>
+        <div className={`x-form-label-${labelAlign}`}>{children}</div>
+      </form>
+    </Panel>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/* ItemSelector —— 复刻 Ext.ux.form.ItemSelector（双栏项选择器）       */
+/* 内部即两个 MultiSelect（Available / Selected），中间一列 6 个图标    */
+/* 按钮：toTop/up/add(→)/remove(←)/down/toBottom。                     */
+/* 选择逻辑对齐 ListView multiSelect：单击替换、Ctrl/Cmd 加/减选、      */
+/* Shift 范围选；move 操作在两栏间搬移，arrow 操作重排 Selected 栏。    */
+/* 原 Ext 用 gif 箭头图标（up2.gif 等），本项目无该资源，改用 Button   */
+/* 内箭头字形（⇈ ↑ → ← ↓ ⇊）替代，属保真等效替换。                     */
+/* ------------------------------------------------------------------ */
+export interface ItemSelectorProps {
+  /** 全部可选项（可缺省，与 fromData/toData 二选一）。支持 string[] / [value,text][] / {value,text}[] */
+  data?: Array<string | [string, string] | { value: string; text: string }>;
+  /** 初始选中项的值集合（置于 Selected 栏）。可用逗号分隔串或数组 */
+  value?: string | Array<string | number>;
+  /** Available 栏数据（与 data/value 二选一） */
+  fromData?: Array<string | [string, string] | { value: string; text: string }>;
+  /** Selected 栏初始数据（与 data/value 二选一） */
+  toData?: Array<string | [string, string] | { value: string; text: string }>;
+  /** Available 栏标题（默认 Available） */
+  fromLegend?: string;
+  /** Selected 栏标题（默认 Selected） */
+  toLegend?: string;
+  fromName?: string;
+  toName?: string;
+  /** 每栏列表宽度（px，默认 180） */
+  width?: number;
+  /** 每栏列表高度（px，默认 180） */
+  height?: number;
+  /** getValue 分隔符（默认 ,） */
+  delimiter?: string;
+  /** 隐藏导航图标按钮（默认 false，全部显示） */
+  hideNavIcons?: boolean;
+  drawTopIcon?: boolean;
+  drawUpIcon?: boolean;
+  drawAddIcon?: boolean;
+  drawRemoveIcon?: boolean;
+  drawDownIcon?: boolean;
+  drawBottomIcon?: boolean;
+  disabled?: boolean;
+  id?: string;
+  cls?: string;
+  style?: CSSProperties;
+  /** 选中值变化时回调（回传 Selected 栏值数组） */
+  onChange?: (value: string[]) => void;
+}
+export interface ItemSelectorHandle {
+  getValue: () => string;
+  getRawValue: () => string[];
+  getSelected: () => Array<{ value: string; text: string }>;
+  setValue: (v: string | Array<string | number>) => void;
+  /** 将全部项移回 Available 栏 */
+  reset: () => void;
+  clear: () => void;
+  add: () => void;
+  remove: () => void;
+  up: () => void;
+  down: () => void;
+  toTop: () => void;
+  toBottom: () => void;
+  disable: () => void;
+  enable: () => void;
+  focus: () => void;
+}
+type ISItem = { value: string; text: string };
+
+function normalizeItems(
+  raw?: Array<string | [string, string] | { value: string; text: string }>,
+): ISItem[] {
+  if (!raw) return [];
+  return raw.map((r) => {
+    if (typeof r === 'string') return { value: r, text: r };
+    if (Array.isArray(r)) return { value: String(r[0]), text: String(r[1]) };
+    return { value: String(r.value), text: String(r.text) };
+  });
+}
+function toArr(v?: string | Array<string | number>): string[] {
+  if (v == null) return [];
+  if (typeof v === 'string') return v === '' ? [] : v.split(',').map((s) => s.trim());
+  return v.map((x) => String(x));
+}
+
+export const ItemSelector = forwardRef<ItemSelectorHandle, ItemSelectorProps>(
+  function ItemSelector(props, ref) {
+    const {
+      data,
+      value,
+      fromData,
+      toData,
+      fromLegend = 'Available',
+      toLegend = 'Selected',
+      fromName,
+      toName,
+      width = 180,
+      height = 180,
+      delimiter = ',',
+      hideNavIcons = false,
+      drawTopIcon = true,
+      drawUpIcon = true,
+      drawAddIcon = true,
+      drawRemoveIcon = true,
+      drawDownIcon = true,
+      drawBottomIcon = true,
+      disabled = false,
+      id,
+      cls,
+      style,
+      onChange,
+    } = props;
+
+    // 初始拆分：data+value 形态 → 全量 data 减去 value 为 Available，value 为 Selected
+    const initial = useMemo<{ from: ISItem[]; to: ISItem[] }>(() => {
+      if (fromData || toData) {
+        return { from: normalizeItems(fromData), to: normalizeItems(toData) };
+      }
+      const all = normalizeItems(data);
+      const sel = new Set(toArr(value));
+      return {
+        from: all.filter((it) => !sel.has(it.value)),
+        to: all.filter((it) => sel.has(it.value)),
+      };
+    }, []); // 仅初始化一次
+
+    const [fromItems, setFromItems] = useState<ISItem[]>(initial.from);
+    const [toItems, setToItems] = useState<ISItem[]>(initial.to);
+    const [fromSel, setFromSel] = useState<Set<string>>(new Set());
+    const [toSel, setToSel] = useState<Set<string>>(new Set());
+    const [disabledState, setDisabledState] = useState(disabled);
+    const fromAnchor = useRef<number | null>(null);
+    const toAnchor = useRef<number | null>(null);
+    // 同步镜像 toItems（每次变更即时更新），使 getValue 在 setValue 等命令式调用后
+    // 立即可读最新值（对齐 Ext 同步 store 行为；React setState 本身异步）。
+    const toItemsRef = useRef<ISItem[]>(initial.to);
+    toItemsRef.current = toItems;
+
+    const fireChange = useCallback(
+      (to: ISItem[]) => {
+        onChange?.(to.map((it) => it.value));
+      },
+      [onChange],
+    );
+
+    const onItemClick = useCallback(
+      (side: 'from' | 'to', index: number, e: React.MouseEvent) => {
+        if (disabledState) return;
+        const items = side === 'from' ? fromItems : toItems;
+        const setSel = side === 'from' ? setFromSel : setToSel;
+        const anchor = side === 'from' ? fromAnchor : toAnchor;
+        const value = items[index].value;
+        setSel((prev) => {
+          const next = new Set(prev);
+          if (e.shiftKey && anchor.current != null) {
+            const [a, b] = [anchor.current, index].sort((x, y) => x - y);
+            for (let i = a; i <= b; i++) next.add(items[i].value);
+          } else if (e.ctrlKey || e.metaKey) {
+            if (next.has(value)) next.delete(value);
+            else next.add(value);
+            anchor.current = index;
+          } else {
+            next.clear();
+            next.add(value);
+            anchor.current = index;
+          }
+          return next;
+        });
+      },
+      [disabledState, fromItems, toItems],
+    );
+
+    const add = useCallback(() => {
+      if (disabledState || fromSel.size === 0) return;
+      const moved = fromItems.filter((it) => fromSel.has(it.value));
+      const restFrom = fromItems.filter((it) => !fromSel.has(it.value));
+      const nextTo = [...toItems, ...moved];
+      setFromItems(restFrom);
+      setToItems(nextTo);
+      toItemsRef.current = nextTo;
+      setToSel(new Set([...toSel, ...moved.map((m) => m.value)]));
+      setFromSel(new Set());
+      fireChange(nextTo);
+    }, [disabledState, fromItems, toItems, fromSel, toSel, fireChange]);
+
+    const remove = useCallback(() => {
+      if (disabledState || toSel.size === 0) return;
+      const moved = toItems.filter((it) => toSel.has(it.value));
+      const restTo = toItems.filter((it) => !toSel.has(it.value));
+      const nextFrom = [...fromItems, ...moved];
+      setToItems(restTo);
+      toItemsRef.current = restTo;
+      setFromItems(nextFrom);
+      setFromSel(new Set([...fromSel, ...moved.map((m) => m.value)]));
+      setToSel(new Set());
+      fireChange(restTo);
+    }, [disabledState, fromItems, toItems, fromSel, toSel, fireChange]);
+
+    const reorder = useCallback(
+      (mode: 'up' | 'down' | 'top' | 'bottom') => {
+        if (disabledState || toSel.size === 0) return;
+        const arr = toItems;
+        const selIdx = arr
+          .map((it, i) => (toSel.has(it.value) ? i : -1))
+          .filter((i) => i >= 0);
+        if (selIdx.length === 0) return;
+        const next = [...arr];
+        if (mode === 'up') {
+          for (const i of [...selIdx].sort((a, b) => a - b)) {
+            if (i > 0) [next[i - 1], next[i]] = [next[i], next[i - 1]];
+          }
+        } else if (mode === 'down') {
+          for (const i of [...selIdx].sort((a, b) => b - a)) {
+            if (i < next.length - 1) [next[i], next[i + 1]] = [next[i + 1], next[i]];
+          }
+        } else if (mode === 'top') {
+          const sel = next.filter((it) => toSel.has(it.value));
+          const rest = next.filter((it) => !toSel.has(it.value));
+          next.length = 0;
+          next.push(...sel, ...rest);
+        } else {
+          const sel = next.filter((it) => toSel.has(it.value));
+          const rest = next.filter((it) => !toSel.has(it.value));
+          next.length = 0;
+          next.push(...rest, ...sel);
+        }
+        setToItems(next);
+        toItemsRef.current = next;
+      },
+      [disabledState, toItems, toSel],
+    );
+
+    useImperativeHandle(ref, () => ({
+      getValue: () => toItemsRef.current.map((it) => it.value).join(delimiter),
+      getRawValue: () => toItemsRef.current.map((it) => it.value),
+      getSelected: () => toItemsRef.current.map((it) => ({ ...it })),
+      setValue: (v) => {
+        const sel = new Set(toArr(v as string | Array<string | number>));
+        const all = [...fromItems, ...toItems];
+        const toNext = all.filter((it) => sel.has(it.value));
+        const fromNext = all.filter((it) => !sel.has(it.value));
+        setToItems(toNext);
+        toItemsRef.current = toNext;
+        setFromItems(fromNext);
+        setFromSel(new Set());
+        setToSel(new Set(sel));
+        fireChange(toNext);
+      },
+      reset: () => {
+        setFromItems((prevFrom) => [...prevFrom, ...toItems]);
+        setToItems([]);
+        toItemsRef.current = [];
+        setFromSel(new Set());
+        setToSel(new Set());
+        fireChange([]);
+      },
+      clear: () => {
+        setFromItems((prevFrom) => [...prevFrom, ...toItems]);
+        setToItems([]);
+        toItemsRef.current = [];
+        setFromSel(new Set());
+        setToSel(new Set());
+        fireChange([]);
+      },
+      add,
+      remove,
+      up: () => reorder('up'),
+      down: () => reorder('down'),
+      toTop: () => reorder('top'),
+      toBottom: () => reorder('bottom'),
+      disable: () => setDisabledState(true),
+      enable: () => setDisabledState(false),
+      focus: () => {},
+    }));
+
+    const showTop = drawTopIcon && !hideNavIcons;
+    const showUp = drawUpIcon && !hideNavIcons;
+    const showAdd = drawAddIcon && !hideNavIcons;
+    const showRemove = drawRemoveIcon && !hideNavIcons;
+    const showDown = drawDownIcon && !hideNavIcons;
+    const showBottom = drawBottomIcon && !hideNavIcons;
+
+    const renderList = (side: 'from' | 'to') => {
+      const items = side === 'from' ? fromItems : toItems;
+      const sel = side === 'from' ? fromSel : toSel;
+      const legend = side === 'from' ? fromLegend : toLegend;
+      const name = side === 'from' ? fromName : toName;
+      return (
+        <fieldset className="x-fieldset x-multiselect" disabled={disabledState}>
+          <legend className="x-fieldset-header">{legend}</legend>
+          <div className="x-fieldset-bwrap">
+            <div
+              className="x-fieldset-body ux-mselect"
+              style={{ width, height, ...(name ? { 'aria-label': name } : {}) }}
+              onDoubleClick={(e) => {
+                const t = e.target as HTMLElement;
+                const node = t.closest('.ux-mselect-item') as HTMLElement | null;
+                if (!node || !node.dataset.value) return;
+                const v = node.dataset.value;
+                if (side === 'from') {
+                  const moved = fromItems.filter((it) => it.value === v);
+                  setFromItems(fromItems.filter((it) => it.value !== v));
+                  const nextTo = [...toItems, ...moved];
+                  setToItems(nextTo);
+                  toItemsRef.current = nextTo;
+                  setToSel(new Set([...toSel, v]));
+                  setFromSel(new Set());
+                  fireChange(nextTo);
+                } else {
+                  const moved = toItems.filter((it) => it.value === v);
+                  const nextTo = toItems.filter((it) => it.value !== v);
+                  setToItems(nextTo);
+                  toItemsRef.current = nextTo;
+                  setFromItems([...fromItems, ...moved]);
+                  setFromSel(new Set([...fromSel, v]));
+                  setToSel(new Set());
+                  fireChange(nextTo);
+                }
+              }}
+            >
+              {items.map((it, i) => {
+                const isSel = sel.has(it.value);
+                return (
+                  <div
+                    key={it.value}
+                    data-value={it.value}
+                    className={['ux-mselect-item', isSel ? 'ux-mselect-selected' : '']
+                      .filter(Boolean)
+                      .join(' ')}
+                    title={it.text}
+                    onClick={(e) => onItemClick(side, i, e)}
+                  >
+                    {it.text}
+                  </div>
+                );
+              })}
+            </div>
+          </div>
+        </fieldset>
+      );
+    };
+
+    return (
+      <span
+        id={id}
+        className={['x-itemselector', disabledState ? 'x-item-disabled' : '', cls]
+          .filter(Boolean)
+          .join(' ')}
+        style={style}
+      >
+        {renderList('from')}
+        <span className="x-itemselector-actions">
+          {showTop && (
+            <Button scale="small" text="⇈" onClick={() => reorder('top')} disabled={disabledState} />
+          )}
+          {showUp && (
+            <Button scale="small" text="↑" onClick={() => reorder('up')} disabled={disabledState} />
+          )}
+          {showAdd && (
+            <Button scale="small" text="→" onClick={add} disabled={disabledState} />
+          )}
+          {showRemove && (
+            <Button scale="small" text="←" onClick={remove} disabled={disabledState} />
+          )}
+          {showDown && (
+            <Button scale="small" text="↓" onClick={() => reorder('down')} disabled={disabledState} />
+          )}
+          {showBottom && (
+            <Button scale="small" text="⇊" onClick={() => reorder('bottom')} disabled={disabledState} />
+          )}
+        </span>
+        {renderList('to')}
+        <input type="hidden" name={toName || fromName} value={toItems.map((it) => it.value).join(delimiter)} />
+      </span>
+    );
+  },
+);
+ItemSelector.displayName = 'ItemSelector';