react-extjs 0.0.1

package/src/components/FieldReplicator.tsx

@@ -0,0 +1,135 @@
+import React, { forwardRef, useCallback, useImperativeHandle, useRef, useState } from 'react';
+import { TextField } from './Form';
+
+/**
+ * 保真 Ext.ux.FieldReplicator（一个挂载到字段上的 plugin）。
+ *
+ * Ext 行为（examples/ux/FieldReplicator.js）：字段被填写（由空变非空）时，
+ * 在其后插入一个克隆字段；字段被清空（由非空变空）且并非唯一一个时，将其移除。
+ * 始终保持末尾有一个空字段供继续输入，最少 1 个。
+ *
+ * React 中以受控数组 values[] 等价表达：填满末尾空字段 → push 一个新空字段；
+ * 清空某个非末尾字段 → splice 移除该字段。TAB 按 DOM 自然顺序在字段间移动，
+ * 等价于 Ext 的 focusNext/focusPrev 拦截。
+ */
+
+export interface FieldReplicatorHandle {
+  /** 读取所有非空当前值（汇总各克隆字段的 getValue） */
+  getValues: () => string[];
+  /** 重置为初始数量的空字段 */
+  reset: () => void;
+}
+
+export interface FieldReplicatorProps {
+  /** 被复制的字段组件，默认 TextField（对齐 Ext 任意 Field 可挂 plugin） */
+  as?: React.ComponentType<any>;
+  /** 传给每个克隆字段的共享 props（name / width / placeholder 等） */
+  fieldProps?: Record<string, any>;
+  /** 初始字段数量，默认 1 */
+  initialCount?: number;
+  /**
+   * 字段 label（可选）。对齐 Ext.ux.FieldReplicator 通过 cloneConfig() 复制 fieldLabel 的行为：
+   * 每个克隆字段都带同样的 label，渲染在各自行左侧（与 FormLayout 一致），而非整组顶部一个。
+   */
+  label?: string;
+  labelAlign?: 'left' | 'top' | 'right';
+  labelWidth?: number;
+  labelPad?: number;
+  labelSeparator?: string;
+  id?: string;
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+export const FieldReplicator = forwardRef<FieldReplicatorHandle, FieldReplicatorProps>(
+  (
+    {
+      as: FieldComp = TextField,
+      fieldProps = {},
+      initialCount = 1,
+      label,
+      labelAlign = 'left',
+      labelWidth = 100,
+      labelPad = 5,
+      labelSeparator = ':',
+      id,
+      className,
+      style,
+    },
+    ref,
+  ) => {
+    const count = Math.max(1, initialCount);
+    const initValues = useRef<string[]>(Array.from({ length: count }, () => ''));
+    const [values, setValues] = useState<string[]>(initValues.current);
+
+    // 镜像最新值，供命令式句柄同步读取（避免 React setState 异步读旧值）
+    const valuesRef = useRef<string[]>(values);
+    valuesRef.current = values;
+
+    const handleChange = useCallback((index: number, v: string) => {
+      setValues((prev) => {
+        const next = [...prev];
+        next[index] = v;
+        if (v === '') {
+          // 清空某字段：若不是最后一个则移除（对齐 Ext onChange 的 blank→remove 分支）
+          if (index !== next.length - 1) {
+            next.splice(index, 1);
+          }
+        } else if (index === next.length - 1) {
+          // 填充满最后一个空字段：追加一个新的空字段（对齐 Ext insert clone）
+          next.push('');
+        }
+        return next;
+      });
+    }, []);
+
+    useImperativeHandle(
+      ref,
+      () => ({
+        getValues: () => valuesRef.current.filter((v) => v !== ''),
+        reset: () => setValues(Array.from({ length: count }, () => '')),
+      }),
+      [count],
+    );
+
+  return (
+    <div
+      id={id}
+      className={['x-ux-fieldreplicator', className].filter(Boolean).join(' ')}
+      style={style}
+    >
+      {values.map((v, i) => {
+        const isTop = labelAlign === 'top';
+        const labelStyle: React.CSSProperties = isTop
+          ? { width: 'auto' }
+          : { width: `${labelWidth}px` };
+        const elementStyle: React.CSSProperties = isTop
+          ? { paddingLeft: 0 }
+          : { paddingLeft: `${labelWidth + labelPad}px` };
+        const itemClass = ['x-form-item', `x-form-label-${labelAlign}`].filter(Boolean).join(' ');
+        return (
+          <div key={i} className={itemClass} style={{ marginBottom: 4 }}>
+            {label && (
+              <label style={labelStyle} className="x-form-item-label">
+                {label}
+                {labelSeparator}
+              </label>
+            )}
+            <div className="x-form-element" style={elementStyle}>
+              <FieldComp
+                {...fieldProps}
+                id={fieldProps.id ? `${fieldProps.id}-${i}` : undefined}
+                value={v}
+                onChange={(val: string) => handleChange(i, val)}
+              />
+            </div>
+            <div className="x-form-clear-left"></div>
+          </div>
+        );
+      })}
+    </div>
+  );
+  },
+);
+
+FieldReplicator.displayName = 'FieldReplicator';

package/src/components/FieldSet.tsx

@@ -0,0 +1,149 @@
+/**
+ * Ext.form.FieldSet 保真复刻（来源 src/widgets/form/FieldSet.js + ext-all.css .x-fieldset*）
+ *
+ * 保真契约：
+ * - onRender：fieldset.x-fieldset；当 title/header/checkboxToggle 时追加 legend.x-fieldset-header。
+ * - legend 内含折叠工具 div.x-tool.x-tool-toggle（collapsible）或 input（checkboxToggle），
+ *   以及标题 span.x-fieldset-header-text。
+ * - 主体 wrapper：div.x-fieldset-bwrap > div.x-fieldset-body（承载子项/字段）。
+ * - 内容宽度 = 总宽 - 左右 border(1+1) - 左右 padding(10+10) = 总宽 - 22（ext-all.css 用 content-box，
+ *   golden 内联 style.width 即内容宽，offsetWidth = 总宽）。
+ * - 折叠态：fieldset 追加 x-panel-collapsed（非 x-fieldset-collapsed）；CSS 隐藏 bwrap
+ *   （visibility:hidden + 移出视口）并把工具图标切到展开位（.x-panel-collapsed .x-tool-toggle）。
+ * - 工具图标背景来自 .x-tool 的 tool-sprites.gif（position 0 -60px 折叠/0 -75px 展开），
+ *   与 Panel/Window 共用同一 sprite，复用 ext-all.css 像素一致。
+ * 仅重写折叠交互（useState + onClick），DOM/class 与 Ext JS 3.2.1 完全一致。
+ */
+import {
+  useState,
+  useRef,
+  forwardRef,
+  useImperativeHandle,
+  useMemo,
+  Children,
+  Fragment,
+  type ReactNode,
+  type CSSProperties,
+} from 'react';
+
+export interface FieldSetProps {
+  /** 图例标题文本。 */
+  title?: ReactNode;
+  /** 是否可折叠（legend 渲染折叠工具）。默认 false。 */
+  collapsible?: boolean;
+  /** 初始折叠态。默认 false（展开）。 */
+  collapsed?: boolean;
+  /** legend 前渲染复选框控制展开/折叠（本期未实现复选框形态，保留接口）。 */
+  checkboxToggle?: boolean;
+  /** 总宽度（含 border/padding）。省略则自适应。 */
+  width?: number;
+  /** 附加类名。 */
+  className?: string;
+  style?: CSSProperties;
+  children?: ReactNode;
+}
+
+/**
+ * 命令式动态增删接口（对齐 Ext.form.FieldSet.add / remove）。
+ * add 返回该项的稳定 id，remove(id) 移除它；getItems 返回当前所有项 id。
+ */
+export interface FieldSetHandle {
+  add: (node: ReactNode, id?: string) => string;
+  remove: (id: string) => void;
+  getItems: () => string[];
+}
+
+export const FieldSet = forwardRef<FieldSetHandle, FieldSetProps>(function FieldSet(
+  { title, collapsible = false, collapsed = false, checkboxToggle = false, width, className, style, children },
+  ref,
+) {
+  const [isCollapsed, setCollapsed] = useState(collapsed);
+  // 双轨：children prop 为静态项来源（受控——父级重渲染时其中受控字段能正常收到新 props），
+  // 运行时 add/remove 维护独立的 dynamicItems / removedSeeds 状态，绝不会被 prop 变更冲掉。
+  // 用 Fragment 带 key 渲染，避免额外包裹 DOM 节点破坏既有保真像素基线。
+  // 注：早期实现把 children 播种进 state 一次后只渲染该快照，导致 FieldSet 内受控字段
+  // （如 ComboBox 的 value）在父级重渲染时收不到新 props，下拉选择不回显。此处改为实时渲染 children。
+  const seedItems = useMemo<{ id: string; node: ReactNode }[]>(
+    () =>
+      Children.toArray(children)
+        // Children.toArray 把单个 Fragment 当成 1 个 opaque child（不二次展开其内部），
+        // 故需先把 Fragment 扁平为数组，否则外层 Fragment 内的多项会被当作 1 项播种，
+        // 导致「渲染出 N 项、getItems 却只返回 1 项」的不一致。
+        .flatMap((c) => (c && (c as any).type === Fragment ? Children.toArray((c as any).props.children) : [c]))
+        .map((c, i) => ({ id: `seed-${i}`, node: c })),
+    [children],
+  );
+  const [dynamicItems, setDynamicItems] = useState<{ id: string; node: ReactNode }[]>([]);
+  const [removedSeeds, setRemovedSeeds] = useState<Set<string>>(new Set());
+  const dynCounter = useRef(0);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      add: (node: ReactNode, id?: string) => {
+        const key = id ?? `dyn-${dynCounter.current++}`;
+        setDynamicItems((prev) => [...prev, { id: key, node }]);
+        return key;
+      },
+      remove: (id: string) => {
+        if (id.startsWith('dyn-')) {
+          setDynamicItems((prev) => prev.filter((it) => it.id !== id));
+        } else {
+          setRemovedSeeds((prev) => new Set(prev).add(id));
+        }
+      },
+      getItems: () => [
+        ...seedItems.filter((s) => !removedSeeds.has(s.id)).map((s) => s.id),
+        ...dynamicItems.map((it) => it.id),
+      ],
+    }),
+    [seedItems, dynamicItems, removedSeeds],
+  );
+
+  // 内容宽度 = 总宽 - 左右 border(1+1) - 左右 padding(10+10)
+  const contentWidth = width != null ? width - 22 : undefined;
+
+  const fsClass = ['x-fieldset', isCollapsed ? 'x-panel-collapsed' : '', className]
+    .filter(Boolean)
+    .join(' ');
+
+  const fsStyle: CSSProperties = {
+    ...(contentWidth != null ? { width: contentWidth } : {}),
+    ...style,
+  };
+
+  const hasHeader = title != null || collapsible || checkboxToggle;
+
+  return (
+    <fieldset className={fsClass} style={fsStyle}>
+      {hasHeader && (
+        <legend className="x-fieldset-header x-unselectable">
+          {collapsible && (
+            <div
+              className="x-tool x-tool-toggle"
+              onClick={() => setCollapsed((c) => !c)}
+            >
+              {' '}
+            </div>
+          )}
+          {title != null && <span className="x-fieldset-header-text">{title}</span>}
+        </legend>
+      )}
+      <div className="x-fieldset-bwrap">
+        <div
+          className="x-fieldset-body"
+          style={contentWidth != null ? { width: contentWidth } : undefined}
+        >
+          {seedItems
+            .filter((it) => !removedSeeds.has(it.id))
+            .map((it) => (
+              <Fragment key={it.id}>{it.node}</Fragment>
+            ))}
+          {dynamicItems.map((it) => (
+            <Fragment key={it.id}>{it.node}</Fragment>
+          ))}
+        </div>
+      </div>
+    </fieldset>
+  );
+});

package/src/components/FitLayout.tsx

@@ -0,0 +1,76 @@
+import React from 'react';
+
+export interface FitItem {
+  /** 面板标题（渲染 x-panel-header）。省略则无 header、整高即 body。 */
+  title?: string;
+  /** 主体内容（纯文本/HTML 字符串）；也可通过 children 渲染任意 React 节点。 */
+  html?: string;
+  children?: React.ReactNode;
+  /** 透传到 .x-panel-body 的 inline style */
+  bodyStyle?: React.CSSProperties;
+}
+
+export interface FitLayoutProps {
+  /** 容器总宽（px），对齐 Ext.Container width，也是 fit 子面板目标宽。 */
+  width: number;
+  /** 容器总高（px），对齐 Ext.Container height，也是 fit 子面板目标高。 */
+  height: number;
+  /** 唯一子面板配置（FitLayout 仅容纳一个子项）。 */
+  item: FitItem;
+  /** 数据测试 id，挂在根容器上。 */
+  testId?: string;
+  style?: React.CSSProperties;
+  className?: string;
+}
+
+// Ext 3.2.1 实测：x-panel 本身 border 为 0，header 高 26px，body 占剩余（含 1px 底边框，border-box）。
+const HEADER_H = 26;
+
+/**
+ * 复刻 Ext.layout.FitLayout（Ext 3.2.1）。
+ *
+ * DOM 对齐 ContainerLayout(fit) 实测真值（#fitlayout）：
+ *  - 容器根无专属 ct 类（ext-all.css 无 .x-fit-item 等）；
+ *  - 唯一的子面板直接作为容器子节点，setSize 到容器内容区（width × height），铺满整个容器。
+ *
+ * 定位数学：子面板整体宽高 = 容器内容区（无 padding），header 占 26px，body = height-26。
+ * 全部视觉来自 ext-all.css 既有规则（零新增 CSS）。
+ */
+export function FitLayout({
+  width,
+  height,
+  item,
+  testId,
+  style,
+  className = '',
+}: FitLayoutProps) {
+  const rootStyle: React.CSSProperties = { width, height, ...style };
+  const headerH = item.title ? HEADER_H : 0;
+  const bodyH = height - headerH;
+
+  return (
+    <div
+      data-testid={testId}
+      className={['fit-layout-root', className].filter(Boolean).join(' ')}
+      style={rootStyle}
+    >
+      <div className="x-panel" style={{ width, height }}>
+        {item.title && (
+          <div className="x-panel-header x-unselectable" unselectable="on">
+            <span className="x-panel-header-text">{item.title}</span>
+          </div>
+        )}
+        <div className="x-panel-bwrap">
+          <div
+            className={['x-panel-body', !item.title && 'x-panel-body-noheader'].filter(Boolean).join(' ')}
+            style={{ height: bodyH, ...item.bodyStyle }}
+          >
+            {item.html != null ? item.html : item.children}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default FitLayout;